Skip to main content
Neighborhood Design System v5.1.0

Carousel

Draft

A carousel allows users to browse through a series of content items one at a time with navigation controls and optional autoplay. Requires Carousel Item components as children to define individual slides.

Storybook docs (opens in new tab)
Draft. This component is in draft. Its API may change before it is marked Ready. What this means

Preview

Open in Storybook (opens in new tab)

Code

Install 
npm install @fbin-web/neighborhood-core
Import 
import { NbhdCarousel } from '@fbin-web/neighborhood-core';
Usage 
<nbhd-carousel
  slides-per-view="2"
  space-between="16">
  <nbhd-carousel-item>
    <nbhd-flex surface="secondary">
      <nbhd-text
        tag="h2"
        variant="title"
        >Slide 1</nbhd-text
      >
      <nbhd-text tag="p">This is the first slide.</nbhd-text>
      <nbhd-link
        href="go-to-this-link-1"
        aria-label="Learn more about Slide 1"
        >Learn More</nbhd-link
      >
    </nbhd-flex>
  </nbhd-carousel-item>
  <nbhd-carousel-item>
    <nbhd-flex surface="secondary">
      <nbhd-text
        tag="h2"
        variant="title"
        >Slide 2</nbhd-text
      >
      <nbhd-text tag="p">This is the second slide.</nbhd-text>
      <nbhd-link
        href="go-to-this-link-2"
        aria-label="Learn more about Slide 2"
        >Learn More</nbhd-link
      >
    </nbhd-flex>
  </nbhd-carousel-item>
  <nbhd-carousel-item>
    <nbhd-flex surface="secondary">
      <nbhd-text
        tag="h2"
        variant="title"
        >Slide 3</nbhd-text
      >
      <nbhd-text tag="p">This is the third slide.</nbhd-text>
      <nbhd-link
        href="go-to-this-link-3"
        aria-label="Learn more about Slide 3"
        >Learn More</nbhd-link
      >
    </nbhd-flex>
  </nbhd-carousel-item>
  <nbhd-carousel-item>
    <nbhd-flex surface="secondary">
      <nbhd-text
        tag="h2"
        variant="title"
        >Slide 4</nbhd-text
      >
      <nbhd-text tag="p">This is the fourth slide.</nbhd-text>
      <nbhd-link
        href="go-to-this-link-4"
        aria-label="Learn more about Slide 4"
        >Learn More</nbhd-link
      >
    </nbhd-flex>
  </nbhd-carousel-item>
  <nbhd-carousel-item>
    <nbhd-flex surface="secondary">
      <nbhd-text
        tag="h2"
        variant="title"
        >Slide 5</nbhd-text
      >
      <nbhd-text tag="p">This is the fifth slide.</nbhd-text>
      <nbhd-link
        href="go-to-this-link-5"
        aria-label="Learn more about Slide 5"
        >Learn More</nbhd-link
      >
    </nbhd-flex>
  </nbhd-carousel-item>
  <nbhd-carousel-item>
    <nbhd-flex surface="secondary">
      <nbhd-text
        tag="h2"
        variant="title"
        >Slide 6</nbhd-text
      >
      <nbhd-text tag="p">This is the sixth slide.</nbhd-text>
      <nbhd-link
        href="go-to-this-link-6"
        aria-label="Learn more about Slide 6"
        >Learn More</nbhd-link
      >
    </nbhd-flex>
  </nbhd-carousel-item>
</nbhd-carousel>

Usage

  • Without loop, the previous and next buttons are disabled at the first and last slide.
  • When every slide fits in view, the navigation, pagination and play/pause button are hidden.
  • With autoplay set, a play/pause button shows next to the pagination. Rotation pauses while the pointer is over the slides, stops when keyboard focus enters the carousel, and starts paused for visitors who prefer reduced motion. play() and pause() control it from script.

Properties

PropertyAttributeTypeDefaultDescription
variantvariantcardproduct-cardminitronjumbotronhumongotroncustomcustomCarousel content variant.
slidesPerViewslides-per-viewnumber1Number of slides shown at once when using slide transition.
spaceBetweenspace-betweennumber16Space between slides in pixels.
hideNavigationhide-navigationbooleanfalseHide previous/next navigation controls when set to true.
hidePaginationhide-paginationbooleanfalseHide pagination bullets when set to true. With autoplay set, the play/pause button stays visible.
looploopbooleanfalseEnable continuous loop mode. Without it, the previous/next buttons are disabled at the first/last slide.
fadefadebooleanfalseUse fade transition instead of slide transition.
speedspeed5001000200030001000Transition duration in milliseconds.
autoplayautoplay0200030004000500060000Autoplay delay in milliseconds; 0 disables autoplay. When set, a play/pause button shows next to the pagination.
paginationVariantpagination-variantcirclelinecirclePagination style variant.
navigationVariantnavigation-variantprimarysecondaryghostprimaryNavigation button style variant.
navigationPositionnavigation-positionsidebottomsideNavigation control placement.
fullwidthfullwidthbooleanfalseEnable full-width carousel presentation.
keyboardkeyboardbooleantrueEnable keyboard navigation for carousel controls.
breakpointsbreakpointsstring—JSON string map of viewport widths to slidesPerView values.
surfacesurfacenoneprimarysecondaryinverseinverse-secondaryprimarySurface theme for the carousel section.
marginTopmargin-topnonesmallmediumlargenoneAdjust margin above the component.
marginBottommargin-bottomnonesmallmediumlargenoneAdjust margin below the component.
paddingToppadding-topdefaultnonesmallmediumlargedefaultAdjust padding above the component.
paddingBottompadding-bottomdefaultnonesmallmediumlargedefaultAdjust padding below the component.
previousLabelprevious-labelstringPrevious slideAccessible name of the previous-slide button.
nextLabelnext-labelstringNext slideAccessible name of the next-slide button.
paginationLabelpagination-labelstringChoose slideAccessible name of the group of pagination buttons.
slideButtonLabelslide-button-labelstringGo to slide {index}Accessible name of each pagination button; `{index}` is replaced with the slide number.
playLabelplay-labelstringStart slide rotationAccessible name of the autoplay toggle while rotation is paused.
pauseLabelpause-labelstringPause slide rotationAccessible name of the autoplay toggle while slides are rotating.

Events

NameDescriptionEvent Detail
nbhd-slide-changeFired when the carousel changes to a new slide.{ activeIndex: number, previousIndex: number }
nbhd-autoplay-changeFired when automatic slide rotation is started or stopped by the viewer - through the play/pause toggle, play()/pause(), or keyboard focus entering the carousel.{ running: boolean, reason: 'user' | 'focus' }

CSS Parts

NameDescription
baseThe component's base section wrapper.
containerThe container element wrapping all carousel content.
carouselThe Swiper container element.
wrapperThe slides wrapper container.
navigationThe navigation controls container.
navigation-prevThe previous slide navigation button.
navigation-nextThe next slide navigation button.
carousel-navigation-iconThe navigation button SVG icons.
paginationThe pagination controls container.
pagination-rowThe row holding the pagination and the autoplay toggle.
autoplay-controlThe autoplay play/pause toggle button. Rendered when autoplay is set.
autoplay-control-iconThe autoplay toggle's play/pause SVG icon.
carousel-controlsThe container for carousel navigation, pagination, and autoplay controls. 
nbhd-carousel::part(base) {
  /* your styles */
}

CSS Properties

Set these on nbhd-carousel or an ancestor to override the defaults. Token is the design token a default comes from and Value is what it resolves to in core Neighborhood; brands may override them. Properties that adapt to surface follow the light or inverse surface they sit on until you set them.

Minitron

PropertyTokenValue Copy
--nbhd-minitron-reverse-shadow--nbhd-shadow-lg-reverse20px 10px 20px rgb(from #000000 r g b / 0.15)
--nbhd-minitron-shadow--nbhd-shadow-lg-20px 10px 20px rgb(from #000000 r g b / 0.15)

Dependencies

Child components <nbhd-carousel> renders internally. Import them too when you tree-shake.

ContainerReady <nbhd-container> Carousel ItemDraft <nbhd-carousel-item>
Esc
↑ ↓ to move↵ to open