Anatomy
Note: Image not to scale
- Title
- Controls
- Content items
- Pagination Dots (index)
Options
Paging
The carousel component uses "pages" to display nested content in a linear sequence. A continuous group of visible items constitutes a page. By default, the starting page is "1". The carousel can be configured to start on a page other than "1".
Items per page
The carousel can be configured to page automatically (vased on the available width), or by a set number of items.
Guidance
Controls: Top (default)
Carousel controls are placed in the far right top corner of the component by default. This is the preferred option for most use-cases as it offers a predictable layout for users familiar with the carousel UI pattern.
Controls: Bottom
Controls can also be placed below content items, in the far right bottom corner.
Controls: Center
Controls can be positioned to overlap the content items, fixed to the far left and far right of the carousel container. This layout is suitable for use-cases in which it is preferable to maintain white space above and below the content area.
Controls on mobile devices
On mobile devices, controls are hidden by default to permit navigation by swipe only. This behavior is optimal for compact layouts such as smartphones where screen real-estate is limited.
(You may view any of the live demo examples on this page on your mobile device to see this behavior in action).
Custom controls
The carousel can accept custom "previous"/"next" buttons. However, be mindful of visual contrast and accessibility contraints when evaluating design and technical implementation.
Slideshow
The carousel component can be configured as a slideshow. The slideshow option displays one content item at a time and features automatic paging that can be toggled using the "play" / "pause" button.
Accessibility
Handling of current item
To optimize the carousel for interoperability with assistive technologies (e.g. screen -readers), make sure to refer to WAI-ARIA.
Use WAI-ARIA live-region to inform the screen-reader which item is being scrolled into view when using the previous and next buttons - this enables the content of the item to be announced by the screen-reader.
Add aria-labelledby to Carousel Items to allow the screen-reader to read the content items label when moving between them using the arrow keys
Focus
Set keyboard focus on the currently displayed item, upon user interaction with the item.
If carousel is set to page automatically, pause the animation when carousel receives keyboard focus.
Pause the animation when cursor enters hover area of carousel.
Animation / Motion
The carousel honors user preference for reduced motion by disabling animation.
API Reference
Carousel
| Prop | Description | Type | Default | Required |
|---|
CarouselRoot
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| page | Controlled value for the current page | number | ---- | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
| defaultPage | Uncontrolled value for the initial page shown | number | ---- | False |
| onPageChange | callback for page change | () => void | ---- | False |
| itemsPerPage | number of items to move when the page changes @defaut auto | enum number | auto | auto | False |
| onDescendentFocus | callback for internal focus | (index: number) => void | () => undefined | False |
CarouselHeader
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
CarouselHeaderContent
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
CarouselHeaderActions
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
CarouselTitle
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
CarouselPreviousButton
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| icon | enum left | right | center | none | center | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS<{ sm: `(max-width: calc(${string} - 1px))`; md: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; lg: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; xl: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; xxl: `(min-width: ${string}) and (max-width: ${string})`; notS... | ---- | False |
| variant | enum primary | secondary | cta | primary | False | |
| density | enum default | compact | compact | False | |
| isOutline | enum boolean | true | false | ---- | False | |
| asChild | enum boolean | ---- | False |
CarouselNextButton
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| icon | enum left | right | center | none | center | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS<{ sm: `(max-width: calc(${string} - 1px))`; md: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; lg: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; xl: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; xxl: `(min-width: ${string}) and (max-width: ${string})`; notS... | ---- | False |
| variant | enum primary | secondary | cta | primary | False | |
| density | enum default | compact | compact | False | |
| isOutline | enum boolean | true | false | ---- | False | |
| asChild | enum boolean | ---- | False |
CarouselContent
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
CarouselFooter
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
CarouselDots
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| label | The input's label text, required for accessibility | string | Pagination Dots | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| unitName | Specifies the type of element represented by the dots (e.g., "Page") | string | ---- | False |