HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
CarouselView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorShows one slide of several, with controls to move between them.StableSince 0.1.0LayoutUsageimport'@fusion.dev/helix/carousel'import'@fusion.dev/helix-headless/carousel'Preview
API ReferenceRoothelix-carouselShows one slide of several, with controls to move between them.
PropTypeDescriptionautoplaybooleanDefaultfalseWhether the carousel advances on its own.controls"always"|"auto"|"none"Whether the previous and next controls are shown.controlsAlign"center"|"end"|"start"Where the arrows sit along their side of the slides. See indicatorAlign.controlsPlacement"start"|"end"|"top"|"bottom"|"overlay"Which side of the slides the arrows sit on.defaultIndexnumberDefault0The slide to start on, used until index is set.indexnumberThe slide in view, counted from zero.indicatorAlign"center"|"end"|"start"Where the dots sit along their side of the slides.indicatorLabelstringDefault"Slide {index}"The name of each indicator, with {index} filled in.indicatorPlacement"start"|"end"|"top"|"bottom"|"overlay"Which side of the slides the dots sit on.indicatorsLabelstringDefault"{label} slides"The name of the row of indicators, with the carousel's {label} filled in.intervalnumberDefault5000How long each slide is held, in milliseconds. The attribute also takes a
CSS time, such as 5s.labelstringDefault"Carousel"The carousel's name, read by screen readers.loopbooleanDefaultfalseWhether moving past either end wraps to the other.mouseDragbooleanDefaultfalseWhether a mouse can drag the track from slide to slide.nextLabelstringDefault"Next slide"The name of the control that moves to the next slide.orientation"horizontal"|"vertical"Which way the track runs.perViewnumber|"auto"How many slides are shown across the track at once. Absent shows one.previousLabelstringDefault"Previous slide"The name of the control that moves to the previous slide.roleLabelstringDefault"carousel"The word screen readers announce in place of the carousel's role, set as
aria-roledescription. Translate it with the rest of your text, or empty
it to leave the role as group.slideLabelstringDefault"{index} of {count}"The name of each slide, with {index} and {count} filled in.slideRoleLabelstringDefault"slide"The word screen readers announce in place of a slide's role, set as
aria-roledescription. Translate it with the rest of your text.slidesPerMovenumberHow many slides Previous, Next, the indicators, rotation, and a drag move
at a time. Unset moves one. The track stops at every slides-per-moveth
position from the first, and at the last.startLabelstringDefault"Start slide rotation"The name of the rotation control while rotation is stopped.stopLabelstringDefault"Stop slide rotation"The name of the rotation control while rotation is running.
ReadTypeDescriptionpositionsnumberHow many distinct views the track holds, which is what the indicators count.slidesHTMLElement[]The slides, in light-DOM order. Empty on the server, which has no tree.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The slides.next-iconThe glyph on the control that moves to the next slide. Defaults to a caret.previous-iconThe glyph on the control that moves to the previous slide. Defaults to a caret.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the slide in view changes, with the new index as a string in detail.value.helix-selectHelixSelectEventFired before the slide in view changes, with the requested index. Cancelable: cancel it to keep the current slide. Nothing moves, and a drag returns to the slide the index still holds. See handleScroll.
MethodTypeDescriptiongoTo(index: number) => voidMoves to a slide. It wraps past either end only when loop is set.
PartDescriptioncontrolsThe row of controls.indicatorOne indicator. Pressing it moves to its slide.indicator-currentThe indicator for the slide in view, alongside indicator.indicatorsThe row of indicators that shows which slide is in view.liveThe region that announces the slide a move lands on. Visually hidden in the styled tier.nextThe control that moves to the next slide.next-markThe glyph on the next control.previousThe control that moves to the previous slide.previous-markThe glyph on the previous control.rotationThe control that stops and starts rotation.rotation-markThe glyph on the play and pause control.slideThe pane one slide is shown in, and the box the track snaps to.trackThe scroller the slides sit in.
CSS PropertyDescription--carousel-bleedRoom inside the scroller so it does not clip a slide's shadow, border, or focus ring. The default leaves room for --helix-shadow-md, which reaches 16px below its box. A slide with --helix-shadow-lg reaches 44px and needs more.--carousel-block-sizeHeight of a vertical track.--carousel-gapSpace between slides. Your stylesheet sets it, and the component uses it to measure the run.--carousel-paneThe size of one pane. Your stylesheet sets it, and the component uses it to measure the run.--carousel-per-viewHow many slides go across. The component writes it onto the track, so your stylesheet divides the track by the same number the component counts positions from. Read this property to follow per-view, because attribute selectors cannot cover every possible count. Under per-view="auto" the component writes nothing and your stylesheet declares it, so the same name works in both modes. See perView.--carousel-run-endHow far short of a whole pixel the run ends, set on the last slide only. Your stylesheet applies it as margin-inline-end. See runEnd.--carousel-slide-minThe narrowest a slide may be. per-view="auto" uses it to fit slides into the track. It must be a length, because the stylesheet divides by it. When unset, it is the whole track, which shows one slide across.
Custom stateDescriptiondraggingWhile a mouse drags the track, under mouse-drag.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-carouselShows one slide of several, with controls to move between them.
PropTypeDescriptionautoplaybooleanDefaultfalseWhether the carousel advances on its own.controls"always"|"auto"|"none"Whether the previous and next controls are shown.defaultIndexnumberDefault0The slide to start on, used until index is set.indexnumberThe slide in view, counted from zero.indicatorLabelstringDefault"Slide {index}"The name of each indicator, with {index} filled in.indicatorsLabelstringDefault"{label} slides"The name of the row of indicators, with the carousel's {label} filled in.intervalnumberDefault5000How long each slide is held, in milliseconds. The attribute also takes a
CSS time, such as 5s.labelstringDefault"Carousel"The carousel's name, read by screen readers.loopbooleanDefaultfalseWhether moving past either end wraps to the other.mouseDragbooleanDefaultfalseWhether a mouse can drag the track from slide to slide.nextLabelstringDefault"Next slide"The name of the control that moves to the next slide.orientation"horizontal"|"vertical"Which way the track runs.perViewnumber|"auto"How many slides are shown across the track at once. Absent shows one.previousLabelstringDefault"Previous slide"The name of the control that moves to the previous slide.roleLabelstringDefault"carousel"The word screen readers announce in place of the carousel's role, set as
aria-roledescription. Translate it with the rest of your text, or empty
it to leave the role as group.slideLabelstringDefault"{index} of {count}"The name of each slide, with {index} and {count} filled in.slideRoleLabelstringDefault"slide"The word screen readers announce in place of a slide's role, set as
aria-roledescription. Translate it with the rest of your text.slidesPerMovenumberHow many slides Previous, Next, the indicators, rotation, and a drag move
at a time. Unset moves one. The track stops at every slides-per-moveth
position from the first, and at the last.startLabelstringDefault"Start slide rotation"The name of the rotation control while rotation is stopped.stopLabelstringDefault"Stop slide rotation"The name of the rotation control while rotation is running.
ReadTypeDescriptionpositionsnumberHow many distinct views the track holds, which is what the indicators count.slidesHTMLElement[]The slides, in light-DOM order. Empty on the server, which has no tree.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The slides.next-iconThe glyph on the control that moves to the next slide. Defaults to a caret.previous-iconThe glyph on the control that moves to the previous slide. Defaults to a caret.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the slide in view changes, with the new index as a string in detail.value.helix-selectHelixSelectEventFired before the slide in view changes, with the requested index. Cancelable: cancel it to keep the current slide. Nothing moves, and a drag returns to the slide the index still holds. See handleScroll.
MethodTypeDescriptiongoTo(index: number) => voidMoves to a slide. It wraps past either end only when loop is set.
PartDescriptioncontrolsThe row of controls.indicatorOne indicator. Pressing it moves to its slide.indicator-currentThe indicator for the slide in view, alongside indicator.indicatorsThe row of indicators that shows which slide is in view.liveThe region that announces the slide a move lands on. Visually hidden in the styled tier.nextThe control that moves to the next slide.next-markThe glyph on the next control.previousThe control that moves to the previous slide.previous-markThe glyph on the previous control.rotationThe control that stops and starts rotation.rotation-markThe glyph on the play and pause control.slideThe pane one slide is shown in, and the box the track snaps to.trackThe scroller the slides sit in.
CSS PropertyDescription--carousel-gapSpace between slides. Your stylesheet sets it, and the component uses it to measure the run.--carousel-paneThe size of one pane. Your stylesheet sets it, and the component uses it to measure the run.--carousel-per-viewHow many slides go across. The component writes it onto the track, so your stylesheet divides the track by the same number the component counts positions from. Read this property to follow per-view, because attribute selectors cannot cover every possible count. Under per-view="auto" the component writes nothing and your stylesheet declares it, so the same name works in both modes. See perView.--carousel-run-endHow far short of a whole pixel the run ends, set on the last slide only. Your stylesheet applies it as margin-inline-end. See runEnd.--carousel-slide-minThe narrowest a slide may be. per-view="auto" uses it to fit slides into the track. It must be a length, because the stylesheet divides by it. When unset, it is the whole track, which shows one slide across.
Custom stateDescriptiondraggingWhile a mouse drags the track, under mouse-drag.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionAlignmentControls and indicators aligned to the start, center, and end.As Many As FitAs many slides across as the track holds, set by a minimum slide width with no count.As Many As FitAs many slides across as the track holds, set by a minimum slide width with no count.ControlledA controlled carousel, with the slide in view set by your own code.Custom ArrowsArrows of your own on the previous and next controls, and a track a mouse can drag from slide to slide.EventsThe slide in view, reported each time it changes, with nothing sent during a drag.HeroFull-bleed slides with the controls over the picture.Indicator PlacementThe indicators moved to each of the places they can sit.PreviewOne slide at a time, with controls and indicators.PreviewOne slide at a time, with controls and indicators.RotatingA carousel that advances on its own and stops when the pointer rests on it.Several AcrossMore than one slide in view, for a shelf of cards.Several AcrossMore than one slide in view, for a shelf of cards.Several At A TimeA shelf of cards that moves three at a time, with one indicator for each stop.VerticalSlides stacked and scrolled downward.