Carousel

a carousel that cycles through children

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string

"a user friendly label for screen readers"

activeChild

If specified, Carousel will be a controlled component. This means that future slide changes will not work unless you subscribe to onChild function and update activeChild accordingly.

number

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string

"start"

"center"

"end"

"stretch"

"baseline"

children

Array of child nodes to use for slides of the Carousel.

array


<Box>Slide One</Box>
<Box>Slide Two</Box>
<Box>Slide Three</Box>

controls

Whether to show carousel controls and which type of controls.

boolean

true

false

string

"arrows"

"selectors"

fill

Whether to expand to fill all of the available width and height in the parent container.

boolean

true

false

gridArea

The name of the area to place this inside a parent Grid.

string

"a parent grid area name"

height

A fixed height.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"xxlarge"

"any CSS size"

object

{ min: "...", max: "..." }

initialChild

If specified, the index of the first element to be shown. Defaults to 0.

number

margin

The amount of margin around the component.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

onChild

If specified, this function will be called with the active index when the currently active carousel changes. Helpful when using Carousel as a controlled component.

function

() => {}

play

If specified, the number of milliseconds between automatically transitioning to the next child. It will loop through all children indefinitely.

number

width

A fixed width.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"xxlarge"

"any CSS size"

object

{ min: "...", max: "..." }

wrap

If specified, the Carousel children will slide in a connected manner. On the last slide, the next icon is enabled, and will transition into the first slide. On the first slide, the previous icon is enabled and will transition into the last slide. Defaults to false.

boolean

true

false

React/DOM Properties

At its core, the Carousel component is a regular <div> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for div elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

carousel.icons.next

The icon to use for the next image navigation control.

element

<Next />

carousel.animation.duration

The duration of the Carousel animation.

number

carousel.icons.previous

The icon to use for the previous image navigation control.

element

<Previous />

carousel.icons.current

The icon to use on the middle navigation control. One icon per carousel image.

element

<Next />

carousel.icons.color

The color used for Carousel icons.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

carousel.disabled.icons.color

The color used for disabled Carousel icons.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.colors.icon

The color of a given icon.

string

A hex, name, or rgb value.

"black"

object

An object with a color for dark and light modes.

{ dark: #f8f8f8, light: #666666 }

global.edgeSize

The possible sizes for margin.

object


    {
      none: '0px',
      hair: '1px',
      xxsmall: '3px',
      xsmall: '6px',
      small: '12px',
      medium: '24px',
      large: '48px',
      xlarge: '96px',
      responsiveBreakpoint: 'small'
    }