GrCarousel

loop is on by default, and it used to simply reset the index: the strip scrolled back through all the slides. On a ten-slide carousel with autoplay every tenth step was a long backward run.

Now at the boundary of the ring the outermost slide temporarily moves over to the opposite end, the strip travels to it as to an ordinary neighbour, and only after the transition the position is reset without animation. There is no clone here and there cannot be one: the slides arrive through a slot, and a copy of someone else’s node would take its state and its refs along with it.

The model is updated at once, without waiting for the end of the transition: modelValue is about which slide is shown, not about whether the strip has arrived.

<GrCarousel orientation="vertical" class="h-56">
  <GrCarouselSlide label="November">…</GrCarouselSlide>
</GrCarousel>

A vertical strip needs a definite viewport height. The step is computed from it, and without a height the column of slides grows with its content, and “by one slide” means the whole strip at once. If the height is zero, the component says so in a dev build instead of silently drawing a column.

The arrows move over to the axis of motion, the cross-axis scrolling of the page stays with the page (touch-action), and the strip of indicators stays horizontal: it is about choosing a slide, not about the direction of the strip.

<GrCarousel virtual :virtual-overscan="1">
  <GrCarouselSlide label="Slide">…</GrCarouselSlide>
</GrCarousel>

What is virtualised is the inside of a slide, not the slide. The slides arrive through a slot, and the strip cannot refuse to render someone else’s node — but it can ask it not to draw its content. An empty wrapper holds its place in the row and weighs almost nothing, while the pictures and cards leave the DOM.

virtualOverscan is how many slides on either side to draw beyond the current one. It is never less than one: the next slide must be ready before the transition, otherwise the strip would travel onto emptiness and the content would show up already in place. With loop the window is closed together with the strip — the left-hand neighbours of the first slide are the last ones.

The markup of a slide is everyone’s own: for a gallery it is an <img>, for onboarding a heading, a paragraph and a button, for a strip of reviews a card. An array of data would force either a render function or a template prop for every kind of slide, so a slide is a GrCarouselSlide with arbitrary content inside.

A consequence worth knowing about: the component learns the composition of the strip from the slides themselves, at mount time. On the server the strip of indicators comes out empty and is filled in on the next tick on the client — the first client render repeats the server one, and hydration stays intact.

The root is role="group" (or region with landmark) with aria-roledescription="carousel". There is deliberately no default name: aria-roledescription does not count as a name, and a substituted “carousel” would be read by the screen reader twice in a row. So ariaLabel or ariaLabelledby are mandatory, and without them the component warns in dev.

The role of a slide depends on the presence of an indicator, and only on it: with a strip a slide is a tabpanel tied to its tab, without a strip it is a group named “N of M”. The look of the indicator has no effect on the role: dots and thumbnails are one and the same tablist in two skins, otherwise a cosmetic prop would rewrite the accessibility contract.

A slide that is not shown right now is marked inert. That is not polish: the slides lie in one row and are clipped by the viewport, so without it Tab drives off into an invisible slide, and the browser scrolls the container to it and falls out of step with the strip.

The strip is not focusable and is not a scroller — the shift is done by a transform, not by scrolling. The ring of the arrow keys lives at the strip of indicators: ←/→ walk the slides, Home/End go to the ends, the strip holds a single Tab stop. With activationMode="manual" an arrow moves only the focus, and the slide is confirmed by Enter or Space.

The ring of the strip is always closed, regardless of loop: loop governs the arrows and the show, while any slide can be chosen directly in any case.

A cursor over the strip, a gesture in progress and a tab in the background put the countdown on pause: the remainder is kept, and on return the strip counts it down rather than starting the interval anew. Focus that has entered inside stops the show and does not resume it by itself — otherwise the slide would drive away from under the finger while the user reads a link inside it.

The pause button is drawn whenever autoplay is set, and there is nothing to hide it with: APG forbids a moving carousel without a mechanism to stop it.

Under prefers-reduced-motion the show does not start, but the button stays and offers to launch it — “reduce motion” does not mean “take the possibility away”. The global clamp does not help here: it kills CSS, while the countdown is driven by a timer, and the strip would keep travelling for the very person who asked it not to.

A gesture begins only where there is no link, button or field under the pointer: the interactive stuff inside a slide stays interactive. Further, the gesture must exceed a threshold — the larger of 60 px and 15 % of the strip’s width — and run more horizontally than vertically, otherwise it is page scrolling, and the carousel does not intercept it. Vertical scrolling of the page stays with the browser: the strip suppresses only the horizontal.

An interrupted gesture does not turn a slide. The browser takes the pointer away from the page — a system gesture, a call, loss of the window — and the user has not completed anything at that point.

With a single slide the arrows, dots and thumbnails are not drawn at all rather than drawn disabled: a disabled control reports that there is somewhere to go. An empty strip is a v-if on the consumer’s side: the consumer writes the slides, and the component will not substitute a “nothing here” text for them.

In descending order of strength: the slide’s #thumbnail slot, then its thumbnail prop with a URL, then the slide’s number in a tile of the same size. The third option keeps the rhythm of the strip when there is no picture at all; if no slide has supplied a thumbnail with indicators="thumbnails", the component warns in dev.

The component does not look for the first <img> inside a slide: walking the markup does not work on the server, breaks on slides without pictures and hides the contract from the reader.

The #prev and #next slots replace the content of the button, not the button itself: the name, aria-disabled and the behaviour at the edge stay with the component. Otherwise a custom arrow would bring along the duty to repeat the whole contract — and it is most often not repeated.

The tone of the current indicator is taken from the package’s shared scale (tone), not from a colour set of its own. A one-off repaint is still done through --gr-carousel-dot-active: the prop sets the role, the hook sets the value. neutral has no saturated colour, so its current dot (and the frame of the current thumbnail) takes the colour of the main text, --gr-fg, like the neutral counter of GrBadgeWrap. The surface grey will not do here: the inactive dots are drawn with it.

The current dot carries two marks: a fill and an outline around it. A fill alone is not enough — at a diameter of eight pixels it distinguished the dot only by shade, and on a muted tone the difference almost vanished. The outline adds shape, that is, it works where colour is not told apart.

Scrolling to the current thumbnail is computed arithmetically and assigned to the scrollLeft of the strip itself. scrollIntoView is no good here: it moves all the ancestors, the document included — and a carousel that has gone below the fold would drag the page back to itself on every step of autoplay.

• there is no virtualisation — all the slides lie in the DOM. A strip of hundreds of heavy slides requires a solution of its own on the consumer’s side;
• there is no endless strip by cloning — loop rewinds the index, so on the transition from the last slide to the first the strip travels back rather than continuing its motion;
• there is no vertical orientation;
• the arrows lie above the slide — they are meant for a photo, where there is nothing to cover. A slide with text must keep its content away from them with margins at the edges (a 36 px button plus an 8 px gap on each side), otherwise the first letters of a line go under the button. The component cannot move the arrows outside the strip;
• the height is set by the tallest slide — the slides lie in one row. A constant height, if one is needed, is set by the content of the slide.