Fraction carousels
Five carousels with a fraction counter and progress indicator: counter, bar, ring, corner and combined. The count is derived deterministically from the slide index and total. Self-contained (no embla), token-driven and sized.
CarouselFraction
Installation
The styled layer is free and installs like any other ai2 component.
Run the following command
npx shadcn@latest add @ai2/carousel-fractionDependencies, the @ai2/tokens theme and the component file are installed together.
Install dependencies
npm install motion lucide-reactCopy the source
components/ui/carousel-fraction.tsxTS
"use client"
import * as React from "react"
import { ChevronLeft, ChevronRight } from "lucide-react"
import { motion, useReducedMotion } from "motion/react"
import { cn } from "@/lib/utils"
/* Fraction carousel family: 5 self-contained sliders (NO embla, NO radix). Each
carries a "1 / 4" counter and/or a token-colored progress indicator. The number
is formatted deterministically from the index + total that come out of the hook
(no Date.now or Math.random). Each export is a complete carousel: the slides
move horizontally and the arrows change the index. The root carries
data-slot="styled-carousel" and role="region". Color comes ONLY from semantic
tokens; the progress is primary, via alpha color-mix. Gated on framer's
useReducedMotion: under reduced motion the slide changes instantly. */
export type StyledSize = "sm" | "md" | "lg" | "xl"
const trackHeight: Record<StyledSize, string> = {
sm: "h-40",
md: "h-56",
lg: "h-72",
xl: "h-96",
}
const focusRing =
"outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50"
const arrowBtn =
"absolute top-1/2 z-20 inline-flex size-9 -translate-y-1/2 items-center justify-center rounded-full border border-border bg-[color-mix(in_oklab,var(--color-background)_72%,transparent)] text-foreground shadow-sm transition-colors supports-[backdrop-filter]:backdrop-blur hover:bg-background [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 [&_i]:text-base [&_i]:leading-none"
/* Token-surfaced, numbered placeholder panels - for prop-less rendering. */
const panelTones = ["bg-surface-2", "bg-surface-3", "bg-muted", "bg-accent"]
function defaultSlides(count = 4): React.ReactNode[] {
return Array.from({ length: count }, (_, i) => (
<div
key={i}
className={cn(
"flex h-full w-full items-center justify-center",
panelTones[i % panelTones.length]
)}
>
<span className="text-4xl font-semibold tabular-nums text-foreground">{i + 1}</span>
</div>
))
}
function resolveSlides(slides?: React.ReactNode[]): React.ReactNode[] {
return slides && slides.length > 0 ? slides : defaultSlides()
}
/* Ortak index state: sonsuz sarma (wrap) ile prev/next ve dogrudan jump. */
function useCarousel(count: number) {
const [index, setIndex] = React.useState(0)
const total = Math.max(count, 1)
const wrap = React.useCallback((i: number) => ((i % total) + total) % total, [total])
const go = React.useCallback((i: number) => setIndex(wrap(i)), [wrap])
const next = React.useCallback(() => setIndex((p) => wrap(p + 1)), [wrap])
const prev = React.useCallback(() => setIndex((p) => wrap(p - 1)), [wrap])
return { index: Math.min(index, total - 1), setIndex: go, next, prev, total }
}
interface CarouselProps {
className?: string
size?: StyledSize
slides?: React.ReactNode[]
}
/* The main horizontally sliding track: every slide is basis-full, translateX by
index. */
function SlideTrack({
items,
index,
next,
prev,
size,
reduce,
overlay,
}: {
items: React.ReactNode[]
index: number
next: () => void
prev: () => void
size: StyledSize
reduce: boolean | null
overlay?: React.ReactNode
}) {
return (
<div className={cn("relative w-full overflow-hidden rounded-xl border border-border", trackHeight[size])}>
<motion.div
className="flex h-full w-full"
animate={{ x: `-${index * 100}%` }}
transition={reduce ? { duration: 0 } : { type: "spring" as const, stiffness: 320, damping: 34 }}
>
{items.map((slide, i) => (
<div
key={i}
role="group"
aria-roledescription="slide"
aria-label={`${i + 1} of ${items.length}`}
aria-hidden={i !== index}
className="h-full w-full shrink-0 basis-full overflow-hidden"
>
{slide}
</div>
))}
</motion.div>
<button type="button" aria-label="Previous slide" onClick={prev} className={cn(arrowBtn, focusRing, "left-3")}>
<ChevronLeft />
</button>
<button type="button" aria-label="Next slide" onClick={next} className={cn(arrowBtn, focusRing, "right-3")}>
<ChevronRight />
</button>
{overlay}
</div>
)
}
/* Deterministik kesir metni: 1 tabanli. */
function fractionLabel(index: number, total: number) {
return `${index + 1} / ${total}`
}
const badgeBase =
"inline-flex items-center gap-1 rounded-full border border-border bg-[color-mix(in_oklab,var(--color-background)_72%,transparent)] px-2.5 py-1 text-xs font-medium tabular-nums text-foreground shadow-sm supports-[backdrop-filter]:backdrop-blur"
/* Counter: belirgin "1 / 4" sayaci, ilerleme cizgisiz. */
export function CounterCarousel({ className, size = "md", slides }: CarouselProps) {
const reduce = useReducedMotion()
const items = resolveSlides(slides)
const { index, next, prev, total } = useCarousel(items.length)
return (
<div
data-slot="styled-carousel"
role="region"
aria-roledescription="carousel"
aria-label="Gallery"
className={cn("relative w-full", className)}
>
<SlideTrack items={items} index={index} next={next} prev={prev} size={size} reduce={reduce} />
<div className="mt-3 flex items-center justify-center">
<span className="text-sm font-medium tabular-nums text-muted-foreground">
<span className="text-foreground">{index + 1}</span> / {total}
</span>
</div>
</div>
)
}
/* Bar: alt kenarda token renkli ilerleme cubugu + kucuk sayac. */
export function BarCarousel({ className, size = "md", slides }: CarouselProps) {
const reduce = useReducedMotion()
const items = resolveSlides(slides)
const { index, next, prev, total } = useCarousel(items.length)
const pct = ((index + 1) / total) * 100
return (
<div
data-slot="styled-carousel"
role="region"
aria-roledescription="carousel"
aria-label="Gallery"
className={cn("relative w-full", className)}
>
<SlideTrack
items={items}
index={index}
next={next}
prev={prev}
size={size}
reduce={reduce}
overlay={
<div className="absolute inset-x-0 bottom-0 z-10 h-1 bg-[color-mix(in_oklab,var(--color-foreground)_14%,transparent)]">
<motion.div
className="h-full bg-primary"
animate={{ width: `${pct}%` }}
transition={reduce ? { duration: 0 } : { type: "spring" as const, stiffness: 320, damping: 34 }}
/>
</div>
}
/>
<div className="mt-3 flex items-center justify-center">
<span className="text-xs font-medium tabular-nums text-muted-foreground">{fractionLabel(index, total)}</span>
</div>
</div>
)
}
/* Ring: dairesel token ilerleme halkasi, ortasinda kesir. */
export function RingCarousel({ className, size = "md", slides }: CarouselProps) {
const reduce = useReducedMotion()
const items = resolveSlides(slides)
const { index, next, prev, total } = useCarousel(items.length)
const r = 16
const c = 2 * Math.PI * r
const offset = c * (1 - (index + 1) / total)
return (
<div
data-slot="styled-carousel"
role="region"
aria-roledescription="carousel"
aria-label="Gallery"
className={cn("relative w-full", className)}
>
<SlideTrack items={items} index={index} next={next} prev={prev} size={size} reduce={reduce} />
<div className="mt-3 flex items-center justify-center">
<div className="relative inline-flex size-12 items-center justify-center">
<svg viewBox="0 0 40 40" className="size-12 -rotate-90">
<circle
cx="20"
cy="20"
r={r}
fill="none"
strokeWidth="3"
className="stroke-[color-mix(in_oklab,var(--color-foreground)_14%,transparent)]"
/>
<motion.circle
cx="20"
cy="20"
r={r}
fill="none"
strokeWidth="3"
strokeLinecap="round"
className="stroke-primary"
strokeDasharray={c}
animate={{ strokeDashoffset: offset }}
transition={reduce ? { duration: 0 } : { type: "spring" as const, stiffness: 260, damping: 30 }}
/>
</svg>
<span className="absolute text-[11px] font-semibold tabular-nums text-foreground">{index + 1}</span>
</div>
</div>
</div>
)
}
/* Corner: the fraction badge overlaps the top right corner of the track. */
export function CornerCarousel({ className, size = "md", slides }: CarouselProps) {
const reduce = useReducedMotion()
const items = resolveSlides(slides)
const { index, next, prev, total } = useCarousel(items.length)
return (
<div
data-slot="styled-carousel"
role="region"
aria-roledescription="carousel"
aria-label="Gallery"
className={cn("relative w-full", className)}
>
<SlideTrack
items={items}
index={index}
next={next}
prev={prev}
size={size}
reduce={reduce}
overlay={
<span className={cn(badgeBase, "absolute right-3 top-3 z-10")} aria-hidden="true">
{fractionLabel(index, total)}
</span>
}
/>
</div>
)
}
/* Combined: kose rozeti + alt ilerleme cubugu + sayac birlikte. */
export function CombinedCarousel({ className, size = "md", slides }: CarouselProps) {
const reduce = useReducedMotion()
const items = resolveSlides(slides)
const { index, next, prev, total } = useCarousel(items.length)
const pct = ((index + 1) / total) * 100
return (
<div
data-slot="styled-carousel"
role="region"
aria-roledescription="carousel"
aria-label="Gallery"
className={cn("relative w-full", className)}
>
<SlideTrack
items={items}
index={index}
next={next}
prev={prev}
size={size}
reduce={reduce}
overlay={
<>
<span className={cn(badgeBase, "absolute right-3 top-3 z-10")} aria-hidden="true">
{fractionLabel(index, total)}
</span>
<div className="absolute inset-x-0 bottom-0 z-10 h-1 bg-[color-mix(in_oklab,var(--color-foreground)_14%,transparent)]">
<motion.div
className="h-full bg-primary"
animate={{ width: `${pct}%` }}
transition={reduce ? { duration: 0 } : { type: "spring" as const, stiffness: 320, damping: 34 }}
/>
</div>
</>
}
/>
<div className="mt-3 flex items-center justify-center">
<span className="text-sm font-medium tabular-nums text-muted-foreground">
<span className="text-foreground">{index + 1}</span> / {total}
</span>
</div>
</div>
)
}Manual installs skip the @ai2/tokens theme, so add the token CSS from the theming guide or the tone colors will be missing.
Variations
5 takes on the same idea. Each is its own export, and every one accepts a size prop (sm, md, lg, xl) aligned to the base Button scale.
Counter
A prominent 1 / 4 counter under the track, no progress bar.
1
1 / 4
TS
import { CounterCarousel } from "@/components/ui/carousel-fraction"
<CounterCarousel />1
1 / 4
1
1 / 4
1
1 / 4
1
1 / 4
Bar
A token progress bar along the bottom edge plus a small counter.
1
1 / 4
TS
import { BarCarousel } from "@/components/ui/carousel-fraction"
<BarCarousel />1
1 / 4
1
1 / 4
1
1 / 4
1
1 / 4
Ring
A circular token progress ring with the index in the center.
1
1
TS
import { RingCarousel } from "@/components/ui/carousel-fraction"
<RingCarousel />1
1
1
1
1
1
1
1
Corner
A fraction badge overlaid in the top-right corner of the track.
1
TS
import { CornerCarousel } from "@/components/ui/carousel-fraction"
<CornerCarousel />1
1
1
1
Combined
A corner badge, a bottom progress bar and a counter together.
1
1 / 4
TS
import { CombinedCarousel } from "@/components/ui/carousel-fraction"
<CombinedCarousel />1
1 / 4
1
1 / 4
1
1 / 4
1
1 / 4
ai2 Fraction carousels: 5 styled variations on the token system
The ai2 Fraction carousels are a set of 5 decorative button variations from the styled layer of the @ai2 design system, built around carousels with a 1 / 4 fraction counter and a token progress indicator. They are free and MIT licensed, and every color comes from a semantic token, so they theme with the rest of ai2 in light and dark.
Motion runs on framer-motion: framer-motion springs the progress bar, ring and horizontal slide track. The styled layer is opt-in, so the dependency only lands if you use it; the base components stay lean. Under reduced motion, the progress and slide change instantly with no animation.
What is in the ai2 Fraction carousels?
5 exports in one file: Counter, Bar, Ring, Corner and Combined. Each renders a native button and takes a size prop (sm, md, lg, xl) aligned to the base Button. They are separate from the base Button on purpose: the base keeps its clean variant, tone and size axes, while the styled layer carries the effects.
You own the file. Copy the one category file and you have all 5 variations, with no runtime dependency on ai2 itself.
Why use it
- On-system by construction: Every color resolves to an ai2 semantic token, so the buttons follow your theme in light and dark with no extra work.
- Effect without the sprawl: The decorations live in a dedicated styled file, so the base Button keeps its clean, predictable API.
- Accessible and honest: Each renders a real button element, keeps a visible focus ring, and respects prefers-reduced-motion.
Features
- Token-driven color: No hardcoded hex or oklch; the look recolors with your theme tokens.
- framer-motion: framer-motion springs the progress bar, ring and horizontal slide track.
- Reduced-motion aware: Under prefers-reduced-motion, the progress and slide change instantly with no animation.
- Size aligned to the base: Every variation takes sm, md, lg and xl matching the base Button height scale, so styled and base buttons line up in a row.
Production tips
- Use it for emphasis, not everywhere: Styled buttons draw the eye. Reserve them for the one action you want people to take on a screen, and use the base Button for the rest.
- Keep labels as verbs: The decoration adds weight, so a clear action label keeps the button scannable.
- Pick one variation per surface: The variations share a family; using two different ones in the same view competes for attention.
Works with the rest of ai2
The Fraction carousels sit alongside the base Button and the rest of the @ai2 registry. They share the same token file, so a styled action next to a base button or a badge stays visually consistent in both modes.