ui/components/spinner

Spinner

Terminal-inspired TUI spinner with four animation styles. The default snake variant renders a 3×3 pixel grid with a trailing dot that moves clockwise — like a pixelated snake.

Preview

tsx

1 import { Spinner } from "@/components/ui/spinner";2 3 export default function SpinnerDefault() {4   return (5     <div className="flex flex-col items-start gap-6">6       <Spinner />7       <Spinner>8         <span className="text-muted-foreground">Loading...</span>9       </Spinner>10     </div>11   );12 }13

Installation

$pnpm exec dgadd add ui/spinner

[Installs to]src/components/ui/spinner[Item]ui/spinner

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Usage

tsx

1 import { Spinner } from "@/components/ui/spinner";2 3 export default function SpinnerDefault() {4   return (5     <div className="flex flex-col items-start gap-6">6       <Spinner />7       <Spinner>8         <span className="text-muted-foreground">Loading...</span>9       </Spinner>10     </div>11   );12 }13

Examples

Variants

Preview

tsx

1 import { Spinner } from "@/components/ui/spinner";2 3 // Every variant animates inside the same em-square glyph box, so the labels4 // share one left edge without a compensating grid column — and swapping the5 // variant on a live spinner shifts nothing.6 export default function SpinnerVariants() {7   return (8     <div className="flex flex-col items-start gap-4">9       <Spinner variant="snake">10         <span className="font-mono text-sm text-muted-foreground">snake</span>11       </Spinner>12       <Spinner variant="braille">13         <span className="font-mono text-sm text-muted-foreground">braille</span>14       </Spinner>15       <Spinner variant="dots">16         <span className="font-mono text-sm text-muted-foreground">dots</span>17       </Spinner>18       <Spinner variant="pulse">19         <span className="font-mono text-sm text-muted-foreground">pulse</span>20       </Spinner>21     </div>22   );23 }24

Sizes

Preview

tsx

1 import { Spinner } from "@/components/ui/spinner";2 3 export default function SpinnerSizes() {4   return (5     <div className="grid grid-cols-[2rem_auto] items-center justify-start gap-x-3 gap-y-4">6       <Spinner size="sm" />7       <span className="font-mono text-xs text-muted-foreground">sm</span>8       <Spinner size="md" />9       <span className="font-mono text-sm text-muted-foreground">md</span>10       <Spinner size="lg" />11       <span className="font-mono text-base text-muted-foreground">lg</span>12     </div>13   );14 }15

Label Positions

Preview

tsx

1 import { Spinner } from "@/components/ui/spinner";2 3 export default function SpinnerLabelPositions() {4   return (5     <div className="flex flex-col items-start gap-6">6       <Spinner labelPosition="right">7         <span className="text-muted-foreground">right</span>8       </Spinner>9       <Spinner labelPosition="left">10         <span className="text-muted-foreground">left</span>11       </Spinner>12       <Spinner labelPosition="bottom">13         <span className="text-muted-foreground">bottom</span>14       </Spinner>15       <Spinner labelPosition="top">16         <span className="text-muted-foreground">top</span>17       </Spinner>18     </div>19   );20 }21

Gap and Speed

Preview

tsx

1 import { Spinner } from "@/components/ui/spinner";2 3 export default function SpinnerGapAndSpeed() {4   return (5     <div className="flex flex-col items-start gap-4">6       <Spinner gap="none">7         <span className="text-muted-foreground">gap="none"</span>8       </Spinner>9       <Spinner gap="lg">10         <span className="text-muted-foreground">gap="lg"</span>11       </Spinner>12       <Spinner speed={40}>13         <span className="text-muted-foreground">speed=&#123;40&#125; (fast)</span>14       </Spinner>15       <Spinner speed={400}>16         <span className="text-muted-foreground">speed=&#123;400&#125; (slow)</span>17       </Spinner>18     </div>19   );20 }21

API Reference

Spinner

Name	Type	Default	Description
variant	"snake" \| "braille" \| "dots" \| "pulse"	"snake"	Animation style. Snake renders a 3x3 pixel grid; braille, dots, and pulse render text glyph sequences.
size	"sm" \| "md" \| "lg"	"md"	Font size token applied to the glyph and label.
labelPosition	"right" \| "left" \| "top" \| "bottom"	"right"	Placement of the children label relative to the spinner glyph.
gap	"none" \| "sm" \| "md" \| "lg"	"md"	Space between the spinner glyph and its label.
speed	number	—	Frame interval in milliseconds. Overrides the variant default (snake 100, braille 80, dots 300, pulse 80).
children	ReactNode	—	Optional label. When omitted, the spinner uses aria-label="Loading".

CSS variables

Name	Default	Description
--spinner-trail-head	1	Opacity of the snake head dot.
--spinner-trail-body	0.6 (light: 0.7)	Opacity of the dot one step behind the head.
--spinner-trail-tail	0.3 (light: 0.45)	Opacity of the dot two steps behind the head.
--spinner-trail-idle	0.15 (light: 0.32)	Opacity of the perimeter dots the trail has passed.

Accessibility

Notes

Labels

Pass children to Spinner to render a label. The labelPosition prop controls where the label appears relative to the glyph: right (default), left, top, or bottom.

Gap Control

The gap prop controls the space between the spinner glyph and its label. Values: "none" (0), "sm" (4px), "md" (8px, default), "lg" (12px). Works for both horizontal and vertical label positions.

Fixed Glyph Box

All four variants animate inside one 2em-square box that scales with the size prop, so swapping variant or cycling frames never moves the label or reflows the row. 2em is the largest footprint any variant needs — the lg snake grid measures 32px at its 16px font size, and the widest dots frame reserves 3ch.

Snake Variant

A 3×3 grid of dots with a 3-dot trail moving clockwise around the 8-position perimeter. The head, body, tail, and idle alphas come from the --spinner-trail-* variables in spinner.css; the light palette raises the ramp (idle 32% instead of 15%) so the trail stays legible on a light background.

Reduced Motion

When prefers-reduced-motion is active, the animation stops at the first frame. If the preference changes at runtime, the animation responds accordingly.

Speed Override

The speed prop overrides the default frame interval in milliseconds. Default speeds: snake 100ms, braille 80ms, dots 300ms, pulse 80ms.

Source

Install via CLI: pnpm exec dgadd add ui/spinner.

Highlighted source loads after this disclosure opens. Browse the source repository.

Spinner

Installation

Usage

Examples

Variants

Sizes

Label Positions

Gap and Speed

API Reference

Spinner

CSS variables

Accessibility

Notes

Labels

Gap Control

Fixed Glyph Box

Snake Variant

Reduced Motion

Speed Override

Source

View component source (9 files)