## Feature Examples

### Structure
- description: Carousel consists of a content area and controls that enable users to navigate within that area. Content area is an empty container that accepts any kind of components inside of it. Most commonly used with `<Image/>` or `<Card/>`.
- example:
```jsx
<Carousel>
  <StorybookComponents.Placeholder height="100px">
    Content (1/3)
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="100px">
    Content (2/3)
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="100px">
    Content (3/3)
  </StorybookComponents.Placeholder>
</Carousel>;
```

### Size
- description: Control the size of previous/next buttons using \`controlsSize\` prop. It supports 3 sizes:\ - \`medium\` (default) - use in all common cases.\ - \`small\` - use when the carousel is inside content widgets (cards or modals).\ - \`tiny\` - use in especially dense layouts.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Carousel controlsSize="medium">
    <StorybookComponents.Placeholder height="100px">
      Medium (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Medium (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Medium (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel controlsSize="small">
    <StorybookComponents.Placeholder height="100px">
      Small (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Small (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Small (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel controlsSize="tiny">
    <StorybookComponents.Placeholder height="100px">
      Tiny (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Tiny (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Tiny (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
</StorybookComponents.Stack>;
```

### Button Skin
- description: Control the skin of the buttons with the \`buttonSkin\` prop. It supports 4 skins:\ - \`standard\` (default) - use when the buttons are on a light background.\ - \`transparent\` - use when they are on a dark colored background.\ - \`inverted\` - use when they are on a light gray background.\ - \`light\` - use when they are on a dark background.\ \ \`inverted\` and \`light\` skins also serve as alternatives to \`standard\` skin on a light background (use them to give less emphasis on the buttons).
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Carousel>
    <StorybookComponents.Placeholder height="100px">
      Standard (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Standard (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Standard (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel buttonSkin="transparent">
    <StorybookComponents.Placeholder height="100px">
      Transparent (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Transparent (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Transparent (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel buttonSkin="inverted">
    <StorybookComponents.Placeholder height="100px">
      Inverted (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Inverted (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Inverted (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel buttonSkin="light">
    <StorybookComponents.Placeholder height="100px">
      Light (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Light (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Light (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
</StorybookComponents.Stack>;
```

### Button Position
- description: Control the position of the buttons with \`controlsPosition\` prop. It supports 4 options:\ - \`sides\` (default) - use it to display controls on the sides of the content.\ - \`bottom\` - use it to display controls underneath the content.\ - \`overlay\` - use it to display controls directly on top of the content to save horizontal space. Give more emphasis to the controls by dropping a shadow below them with \`showControlsShadow\` prop.\ - \`none\` - use it to hide controls in conjunction with autoplay.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Carousel>
    <StorybookComponents.Placeholder height="100px">
      Sides (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Sides (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Sides (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel controlsPosition="bottom">
    <StorybookComponents.Placeholder height="100px">
      Bottom (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Bottom (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Bottom (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel controlsPosition="overlay">
    <StorybookComponents.Placeholder height="100px">
      Overlay (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Overlay (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Overlay (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel controlsPosition="overlay" showControlsShadow>
    <StorybookComponents.Placeholder height="100px">
      Overlay with button shadows (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Overlay with button shadows (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Overlay with button shadows (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel controlsPosition="none" autoplay>
    <StorybookComponents.Placeholder height="100px">
      None (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      None (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      None (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
</StorybookComponents.Stack>;
```

### Image Position
- description: Control how images are aligned inside of a carousel content area with \`imagesPosition\` prop.\ \ First value controls the alignment on the X-axis (\`left\`, \`center\`, \`right\`), the second value on the Y-axis (\`top\`, \`middle\` or \`bottom\`). Default is center top. Position can also be specified in pixels or %.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column" width="60%">
  <Carousel
    images={[
      {
        src: 'TravelExample1.jpg',
      },
      {
        src: 'TravelExample3.jpg',
      },
    ]}
  />
  <Carousel
    imagesPosition="right bottom"
    images={[
      {
        src: 'TravelExample1.jpg',
      },
      {
        src: 'TravelExample3.jpg',
      },
    ]}
  />
</StorybookComponents.Stack>;
```

### Images Fit
- description: Control how images are displayed when their dimensions do not match container size with \`imagesFit\` prop. It supports all default CSS [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) values, but most commonly used are the following ones:\ - \`contain\` (default) - scaled to maintain its aspect ratio while fitting within the element's content box. Scaled until one axis is filled.\ - \`cover\` - sized to maintain its aspect ratio while filling the element's entire content box.\ - \`fill\` - sized to completely fill the box.\ - \`none\` - keeps original image dimensions.\ - \`scale-down\` - sized as if none or contain were specified, whichever would result in a smaller concrete object size.
- example:
```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" width="45%">
    <Text>Contain</Text>
    <Carousel
      imagesFit="contain"
      images={[
        {
          src: 'TravelExample3.jpg',
        },
        {
          src: 'TravelExample4.jpg',
        },
      ]}
    />

    <Text>Fill</Text>
    <Carousel
      imagesFit="fill"
      images={[
        {
          src: 'TravelExample3.jpg',
        },
        {
          src: 'TravelExample4.jpg',
        },
      ]}
    />
    <Text>Scale-down</Text>
    <Carousel
      imagesFit="scale-down"
      images={[
        {
          src: 'TravelExample3.jpg',
        },
        {
          src: 'TravelExample4.jpg',
        },
      ]}
    />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" width="45%">
    <Text>Cover</Text>
    <Carousel
      imagesFit="cover"
      images={[
        {
          src: 'TravelExample3.jpg',
        },
        {
          src: 'TravelExample4.jpg',
        },
      ]}
    />
    <Text>None</Text>
    <Carousel
      imagesFit="none"
      images={[
        {
          src: 'TravelExample3.jpg',
        },
        {
          src: 'TravelExample4.jpg',
        },
      ]}
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

### Variable width
- description: Specify whether to display a single item at a time or few elements simultaneously using \`variableWidth\` prop. When set to \`true\`, child items will be stacked one after another horizontally.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Carousel>
    <StorybookComponents.Placeholder height="100px">
      Content (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Content (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Content (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel variableWidth={true}>
    <StorybookComponents.Placeholder height="100px" width="400px">
      Content (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px" width="400px">
      Content (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px" width="400px">
      Content (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
</StorybookComponents.Stack>;
```

### Dots
- description: Control whether pagination below the carousel is visible with \`dots\` prop.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Carousel>
    <StorybookComponents.Placeholder height="100px">
      Dots (default) (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Dots (default) (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Dots (default) (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel dots={false}>
    <StorybookComponents.Placeholder height="100px">
      No dots (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      No dots (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      No dots (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
</StorybookComponents.Stack>;
```

### Infinite
- description: Disable users from cycling through content items endlessly by setting \`infinite\` prop value to false. Control whether to display disabled start and end buttons at the end of the cycle or not show them at all with \`controlsStartEnd\` prop.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Carousel infinite={true}>
    <StorybookComponents.Placeholder height="100px">
      Infinite cycle (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Infinite cycle (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Infinite cycle (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel infinite={false}>
    <StorybookComponents.Placeholder height="100px">
      Finite cycle with visible but disabled start/end buttons (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Finite cycle with visible but disabled start/end buttons (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Finite cycle with visible but disabled start/end buttons (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
  <Carousel infinite={false} controlsStartEnd="hidden">
    <StorybookComponents.Placeholder height="100px">
      Finite cycle without start/end buttons (1/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Finite cycle without start/end buttons (2/3)
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder height="100px">
      Finite cycle without start/end buttons (3/3)
    </StorybookComponents.Placeholder>
  </Carousel>
</StorybookComponents.Stack>;
```

### Autoplay
- description: Switch between content items automatically with \`autoplay\` prop. When enabled, slides will change every 3 seconds.
- example:
```jsx
<Carousel autoplay={true}>
  <StorybookComponents.Placeholder height="100px">
    Autoplay (1/3)
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="100px">
    Autoplay (2/3)
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="100px">
    Autoplay (3/3)
  </StorybookComponents.Placeholder>
</Carousel>;
```

### Initial slide
- description: Use \`initialSlideIndex\` prop to set the initial slide as the starting point.
- example:
```jsx
<Carousel initialSlideIndex={1}>
  <StorybookComponents.Placeholder height="100px">
    Other (2/2)
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="100px">
    Initial
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="100px">
    Other (1/2)
  </StorybookComponents.Placeholder>
</Carousel>;
```

## Common Use Case Examples

### Image slideshow
- description: Use Carousel to display a series of content.
- example:
```jsx
<Layout>
  <Cell span={6}>
    <Carousel
      autoplay
      imagesPosition="middle"
      controlsPosition="none"
      images={[
        {
          src: 'TravelExample1.jpg',
        },
        {
          src: 'TravelExample2.jpg',
        },
        {
          src: 'TravelExample3.jpg',
        },
        {
          src: 'TravelExample4.jpg',
        },
        {
          src: 'TravelExample5.jpg',
        },
        {
          src: 'TravelExample6.jpg',
        },
        {
          src: 'TravelExample7.jpg',
        },
      ]}
    />
  </Cell>
</Layout>;
```

### Marketing layout
- description: Use Carousel to display a series of Marketing layouts.
- example:
```jsx
<Carousel
  dots={false}
  buttonSkin="inverted"
  infinite={false}
  controlsStartEnd="hidden"
  controlsPosition="overlay"
  showControlsShadow
>
  <Card>
    <MarketingLayout
      title="Get found on Google"
      description="Boost your site's SEO with the SEO Wiz. Follow your step-by-step plan."
      actions={<Button size="small">Start Now</Button>}
      size="tiny"
      image={
        <Box width="100%" align="right">
          <Image
            width="120px"
            src="PromotionalPromoteMarketingHomeSEO.svg"
            transparent
          />
        </Box>
      }
    />
  </Card>
  <Card>
    <MarketingLayout
      title="Create an email campaign"
      description="Send updates, offers or newsletters & keep in touch."
      actions={<Button size="small">Send a Campaign</Button>}
      size="tiny"
      image={
        <Box width="100%" align="right">
          <Image
            width="120px"
            src="PromotionalPromoteMarketingHomeEmail.svg"
            transparent
          />
        </Box>
      }
    />
  </Card>
  <Card>
    <MarketingLayout
      title="Add Sessions to Get Booked"
      description="Set when this service is offered and the staff who provide it."
      actions={
        <Box gap="6px">
          <Button size="small">Add Sessions</Button>
          <Button size="small" skin="inverted">
            Learn More
          </Button>
        </Box>
      }
      size="tiny"
      image={
        <Box width="100%" align="right">
          <Image
            width="120px"
            src="PromotionalBookingsUpgrade.svg"
            transparent
          />
        </Box>
      }
    />
  </Card>
</Carousel>;
```