content-carousel
Rotate slides on autopilot or on click — galleries, hero banners, walkthroughs.
Features
- Auto-play Rotate on a timer via
auto-play - Manual nav
--back/--nextcommands from plain buttons;rel="prev"/rel="next"positions them - Slide or fade Choose the transition with
slide-animation:slide/fade/track - Swipeable
slide-animation="track"wrapped ingesture-handler - Pauses itself Manual navigation stops auto-play automatically
- Bindable position
.provisionis{ index, count, lastMove }— a progress readout is one Quark rule onprop("provision")
Installation
This package is available in the
<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/neutron@0.2.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/content-carousel@0.1.4/dist/index.umd.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@excom/content-carousel@0.1.4/dist/index.css">npm install @excom/content-carousel<!-- import path to `node_modules` will depend on your build setup -->
<script type="module" src="/node_modules/@excom/content-carousel"></script>
<link rel="stylesheet" href="/node_modules/@excom/content-carousel">import "@excom/content-carousel";@import "@excom/content-carousel/index.css";Peer dependencies (0)
Packages a consumer must install alongside this one. Workspace deps are bundled.
| Package | Version |
|---|---|
|
Usage
Wrap <content-carousel-slide> elements in a <content-carousel>. Mark one
is-active, or leave it unset to default to the first.
<content-carousel auto-play="5">
<content-carousel-slide is-active>One</content-carousel-slide>
<content-carousel-slide>Two</content-carousel-slide>
<content-carousel-slide>Three</content-carousel-slide>
</content-carousel><content-carousel auto-play="5">
<content-carousel-slide is-active>One</content-carousel-slide>
<content-carousel-slide>Two</content-carousel-slide>
<content-carousel-slide>Three</content-carousel-slide>
</content-carousel>.provision is { index, count, lastMove } — set on connect and after every slide change (a command, auto-play, a slide added / removed, is-active written on a slide), counting only this carousel's own slides. A "2 / 3" readout:
content-carousel {
$slide: prop("provision").index + 1;
$count: prop("provision").count;
[bind-progress] { content: "#{$slide} / #{$count}"; }
}content-carousel {
$slide: prop("provision").index + 1;
$count: prop("provision").count;
[bind-progress] { content: "#{$slide} / #{$count}"; }
}Nothing animates until the first move: last-move is unset until then, so an initial is-active, in markup or written by the app, appears in place. slide-animation="track" renders only the active slide and its two DOM neighbours, so slides must be siblings (a display: contents wrapper around them is fine) and, with three or more slides, a wrap — --next from the last, --back from the first — cuts to the new slide instead of sliding; put it inside gesture-handler
API Reference
Attributes
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
Provision
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events
Type
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements
Child or descendant elements are recognized by and relevant to its functionality.Styles
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
content-carousel
Attributes (5)
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
auto-play
Seconds between automatic slide advances. Unset disables auto-play.
autoPlay
number
nullis-scrubbing
Set when the element is being dragged. Used by CSS only to disable
transition.
isScrubbing
boolean
falseslide-animation
Transition used when the active slide changes.
slideAnimation
string
"slide" | "fade" | "track""slide"auto-play-stopped
Set automatically after manual navigation, or when the element leaves the document (a DOM move keeps auto-play running), to pause auto-play. Set it directly to pause / resume auto-play programmatically.
autoPlayStopped
boolean
falselast-move
Direction of the most recent slide change — drives the CSS animation direction.
is-active moved from one slide to another counts as forward / back by position. Unset until the first move, so the initial slide appears without animating in.
lastMove
string
"forward" | "back"nullProvision (1)
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
provision
Position:
{ index, count, lastMove } — the active slide's index among this carousel's own slides, how many there are, and the direction of the last move. Set on connect and after every change, including slides added / removed and is-active written on a slide. Not reflected as an attribute.
provision
ContentCarouselProvision
Events (3)
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
Type
content-carousel-slide-changed
After any slide change: a command, auto-play, or
is-active moved from one slide to another (a swipe).
Type
ContentCarouselSlideChangedEvent
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
--back--nextRecognized Elements (1)
Child or descendant elements are recognized by content-carousel and relevant to its functionality.
Slides to rotate through. The first, or whichever has
is-active, is shown initially.
Styles (15)
.tag-content-carousel-nextrel="next" (or .tag-content-carousel-next) as the "next slide" nav control..tag-content-carousel-prevrel="prev" (or .tag-content-carousel-prev) as the "previous slide" nav control.
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
--content-carousel-button-size<length>25px--content-carousel-progress<number>0--content-carousel-slide-animation-duration<time>0.25s--content-carousel-transition-ease<easing-function>ease-out@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
:--content-carouselcontent-carousel, .tag-content-carousel:--content-carousel--is-scrubbing[is-scrubbing], [data-scrubbing]:--content-carousel--last-move[last-move], [data-last-move]:--content-carousel--last-move-back[last-move="back"], [data-last-move="back"]:--content-carousel--last-move-forward[last-move="forward"], [data-last-move="forward"]:--content-carousel--slide-animation[slide-animation], [data-slide-animation]:--content-carousel--slide-animation-fade[slide-animation="fade"], [data-slide-animation="fade"]:--content-carousel--slide-animation-slide[slide-animation="slide"], [data-slide-animation="slide"]:--content-carousel--slide-animation-track[slide-animation="track"], [data-slide-animation="track"]content-carousel-slide
Attributes (1)
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
is-active
Marks this as the currently shown slide. The parent
<content-carousel> keeps exactly one slide active. Write it directly (a swipe) and the carousel's provision, last-move and slide-changed event follow.
isActive
boolean
falseProvision (0)
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events (0)
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
Type
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements (0)
Child or descendant elements are recognized by content-carousel-slide and relevant to its functionality.Styles (2)
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
:--content-carousel-slidecontent-carousel-slide, .tag-content-carousel-slide:--content-carousel-slide--is-active[is-active], [aria-current]Release notes (3)
0.1.3
- Track mode hides every slide beyond the active slide's neighbours and no longer animates the first slide into place
0.1.2
- Auto-play tests poll for the advanced slide instead of sleeping a fixed 80 ms (flaked on loaded CI runners); no runtime change
- Fix an issue where
provisiondid not follow slides added or removed, andlast-moveandcontent-carousel-slide-changeddid not followis-activemoving from one slide to another (a swipe): each change sets one provision, and a carousel moved in the DOM no longer sets it again - Update the internal
autoPlayIntervalIdproperty to_autoPlayIntervalId, as its other private properties are named; it was never an attribute, so markup is unaffected
0.1.1
- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources
Release notes
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
Examples
Manual navigation
Invoke --back / --next from a <button command commandfor>. A direct
child with rel="prev" / rel="next" (or
.tag-content-carousel-prev / .tag-content-carousel-next) is
positioned as the nav control for you. If you want swipeable slides, you
must use the carousel in conjunction with the
Fade transition
slide-animation="fade" crossfades instead of sliding.