# saasflare-ui — full reference

Generated from `packages/ui/registry.json`. Each section quotes the component's full prop interface and one @example block lifted from its source. The canonical machine-readable form is `https://ui.saasflare.io/registry.json`.

---

## Accordion

**Description:** Vertically stacked, collapsible sections for FAQs and disclosure lists. One or many panels open at a time.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/accordion.json
```

**Example:**

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@saasflare/ui";
<Accordion type="single" collapsible>
  <AccordionItem value="faq-1">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>Yes, it follows WAI-ARIA patterns.</AccordionContent>
  </AccordionItem>
</Accordion>
```

---

## Alert

**Description:** Inline status banner (info/success/warning/danger) with icon, title, and description for non-blocking messages.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/alert.json
```

**Props:**

```ts
interface AlertProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
  /** Semantic color intent */
  intent?: Intent | "neutral"
  /**
   * Legacy variant prop for backward compatibility.
   * @deprecated Use `intent` instead. "destructive" maps to intent="danger".
   */
  variant?: "default" | "destructive"
}
```

**Example:**

```tsx
import { Alert, AlertTitle, AlertDescription } from "@saasflare/ui";
import { InfoIcon } from "./phosphor";

<Alert intent="info">
  <InfoIcon />
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>This is an informational alert.</AlertDescription>
</Alert>
```

---

## Alert Dialog

**Description:** Modal confirmation for destructive or irreversible actions, with required acknowledge and cancel actions.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/alert-dialog.json
```

**Example:**

```tsx
import { AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogAction, AlertDialogCancel } from "@saasflare/ui";

<AlertDialog>
  <AlertDialogTrigger asChild><Button variant="outline" intent="danger">Delete</Button></AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader><AlertDialogTitle>Are you sure?</AlertDialogTitle></AlertDialogHeader>
    <AlertDialogCancel>Cancel</AlertDialogCancel>
    <AlertDialogAction>Confirm</AlertDialogAction>
  </AlertDialogContent>
</AlertDialog>
```

---

## Aspect Ratio

**Description:** Locks content to a fixed width:height ratio — responsive images, video embeds, and media cards.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/aspect-ratio.json
```

**Props:**

```ts
interface AspectRatioProps
  extends Omit<
      React.ComponentProps<typeof AspectRatioPrimitive.Root>,
      keyof SaasflareComponentProps
    >,
    SaasflareComponentProps {}

/**
 * Constrains its children to a fixed width-to-height ratio.
 *
 * @example
 * <AspectRatio ratio={16 / 9}>
 *   <img src="/image.jpg" alt="Landscape" />
 * </AspectRatio>
 */
function AspectRatio({
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { AspectRatio } from '@saasflare/ui';
<AspectRatio ratio={16 / 9}>
  <img src="/image.jpg" alt="Landscape" />
</AspectRatio>
```

---

## Audio Player

**Description:** Self-contained audio player UI over the native HTML5 element — play/pause, scrubbing, and volume.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/audio-player.json
```

**Props:**

```ts
export interface AudioPlayerProps extends SaasflareComponentProps {
  /** Audio source URL. */
  src: string
  /** Track title. */
  title?: string
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { AudioPlayer } from '@saasflare/ui';
<AudioPlayer src="/podcast-episode.mp3" title="Episode 12" />
```

---

## Aurora Background

**Description:** Animated aurora backdrop — soft blurred color blobs drifting behind hero content.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/aurora-background.json
```

**Props:**

```ts
export interface AuroraBackgroundProps
    extends Omit<ComponentProps<"div">, keyof SaasflareComponentProps | "color">,
        SaasflareComponentProps {
    /**
     * Three ambient blob colors in order: top-left, right, bottom-left.
     * Default: curated peach + blue + violet showcase palette.
     */
    colors?: readonly [string, string, string]
    /** Overall blob opacity (0–1). Applied inline to every blob. Default: `0.55`. */
    intensity?: number
}
```

**Example:**

```tsx
import { AuroraBackground } from "@saasflare/ui"

<AuroraBackground className="min-h-[500px] rounded-2xl p-12">
  <SectionCard title="Production">…</SectionCard>
</AuroraBackground>
```

---

## Avatar

**Description:** User or brand avatar with image, automatic initials fallback, and size variants.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/avatar.json
```

**Props:**

```ts
interface AvatarProps
  extends Omit<React.ComponentProps<typeof AvatarPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Visual size. `"default"` is a deprecated alias for `"md"`. */
  size?: "sm" | "md" | "lg" | "default"
}
```

**Example:**

```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@saasflare/ui";

<Avatar size="lg">
  <AvatarImage src="/user.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
```

---

## Badge

**Description:** Compact label for statuses, counts, and tags, with semantic intent colors and subtle/solid styles.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/badge.json
```

**Props:**

```ts
interface BadgeProps
  extends Omit<
      React.ComponentProps<"span">,
      "onDrag" | "onDragStart" | "onDragEnd" | "onAnimationStart" | "onAnimationEnd" | keyof SaasflareComponentProps
    >,
    Omit<VariantProps<typeof badgeVariants>, "variant">,
    SaasflareComponentProps {
  /** Render as child element (Radix Slot pattern) */
  asChild?: boolean
  /** Semantic color intent */
  intent?: Intent
  /**
   * Visual treatment: `"solid" | "soft" | "outline"`.
   * @remarks `"default" | "destructive" | "secondary"` are deprecated aliases
   * (mapped to a solid/soft variant + intent via {@link LEGACY_VARIANT_MAP});
   * prefer `variant` + `intent` instead.
   */
  variant?: VariantProps<typeof badgeVariants>["variant"] | "default" | "destructive" | "secondary"
}
```

**Example:**

```tsx
import { Badge } from "@saasflare/ui";

<Badge>Default</Badge>
<Badge intent="success" variant="soft">Active</Badge>
<Badge intent="danger" variant="outline" size="sm">Error</Badge>
```

---

## Bar List

**Description:** Horizontal 'top N' ranking list with proportional bar fills. Dashboard staple.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/bar-list.json
```

**Props:**

```ts
export interface BarListProps extends SaasflareComponentProps {
    /** Rows to render. */
    data: BarListItem[]
    /** Formats the numeric value on the right edge. Default: `(n) => n.toLocaleString()`. */
    valueFormatter?: (value: number) => string
    /** Sort rows by value descending. Default: `true`. */
    sortDescending?: boolean
    /** Maximum rows rendered (truncates after sort). */
    limit?: number
    /** Additional class names. */
    className?: string
}
```

**Example:**

```tsx
<BarList
  data={[
    { name: "Germany", value: 4321 },
    { name: "United States", value: 3210 },
    { name: "Brazil", value: 2987 },
  ]}
  valueFormatter={(n) => n.toLocaleString()}
/>
```

---

## Bento Grid

**Description:** Bento-style grid layout for feature galleries with mixed sizes.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/bento-grid.json
```

**Props:**

```ts
export interface BentoGridProps extends SaasflareComponentProps {
  /** Grid items. */
  children: ReactNode
  /** Number of columns at md+ breakpoint. Default: `3` */
  columns?: 2 | 3 | 4
  /** Gap between items in Tailwind spacing units (4 = 1rem). Default: `4` */
  gap?: number
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { BentoGrid, BentoGridItem } from '@saasflare/ui';
<BentoGrid>
  <BentoGridItem colSpan={2}>Wide card</BentoGridItem>
  <BentoGridItem rowSpan={2}>Tall card</BentoGridItem>
  <BentoGridItem>Standard card</BentoGridItem>
</BentoGrid>
```

---

## Blur Fade

**Description:** Entrance animation combining blur, fade, and offset — for elegant on-mount and on-scroll reveals.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/blur-fade.json
```

**Props:**

```ts
export interface BlurFadeProps
  extends Omit<React.ComponentProps<"div">, MotionConflicts | keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Content to animate. */
  children: ReactNode
  /** Animation delay in seconds (use for staggering). Default: `0` */
  delay?: number
  /** Initial blur amount in pixels. Default: `8` */
  blur?: number
  /** Vertical offset in pixels. Default: `12` */
  yOffset?: number
  /** Animation duration in seconds. Default: `0.5` */
  duration?: number
  /** Whether animation triggers only once. Default: `true` */
  once?: boolean
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { BlurFade } from '@saasflare/ui';
<BlurFade>
  <Card>Fades in with blur</Card>
</BlurFade>
```

---

## Border Beam

**Description:** A glowing gradient beam that travels around an element's border. Premium accent for cards and CTAs.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/border-beam.json
```

**Props:**

```ts
export interface BorderBeamProps extends SaasflareComponentProps {
  /** Beam color. Default: `"var(--primary)"` */
  color?: string
  /** Tail fade color. Default: `"transparent"` */
  colorFrom?: string
  /** Animation cycle duration in seconds. Default: `6` */
  duration?: number
  /** Beam length in pixels. Default: `150` */
  size?: number
  /** Border radius to follow (CSS value). Default: `"inherit"` */
  borderRadius?: string
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { BorderBeam } from '@saasflare/ui';
<div className="relative rounded-xl border p-6">
  <BorderBeam />
  <h3>Premium Feature</h3>
</div>
```

---

## Breadcrumb

**Description:** Hierarchical navigation trail showing the user's location, with truncation and custom separators.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/breadcrumb.json
```

**Props:**

```ts
interface BreadcrumbProps extends Omit<React.ComponentProps<"nav">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/**
 * Breadcrumb navigation root — labelled `<nav>` wrapping the trail. Resolves the
 * Saasflare axes and emits `data-surface`/`data-radius`/`data-animated`.
 */
function Breadcrumb({ surface, radius, animated, iconWeight, ...props }: BreadcrumbProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })

  return (
    <nav
      {...props}
      aria-label="breadcrumb"
      data-slot="breadcrumb"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
    />
  )
}
```

**Example:**

```tsx
import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage } from '@saasflare/ui';
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
    <BreadcrumbItem><BreadcrumbPage>Current</BreadcrumbPage></BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

---

## Button

**Description:** The core action element. Three orthogonal axes — variant × intent × size — plus loading and icon slots.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/button.json
```

**Props:**

```ts
interface ButtonProps
  extends Omit<React.ComponentProps<"button">, MotionConflicts>,
    VariantProps<typeof buttonVariants>,
    SaasflareComponentProps {
  /**
   * Render as child element (Radix Slot pattern). Mutually exclusive with the
   * presentational slot props below — when `asChild` is set they are ignored
   * (dev-only `console.warn`) since a Slot cannot own injected DOM children.
   */
  asChild?: boolean
  /** Semantic color intent */
  intent?: Intent
  /** Stretch to full width of container */
  fullWidth?: boolean

  // ── Presentational slots (additive) ──
  /**
   * Node rendered before the label (e.g. a leading icon). Ignored when `asChild`.
   * Intended for non-interactive adornments; mark meaningful icons `aria-hidden`
   * yourself if they are decorative.
   */
  startContent?: React.ReactNode
  /**
   * Node rendered after the label (e.g. a trailing icon). Ignored when `asChild`.
   * Intended for non-interactive adornments.
   */
  endContent?: React.ReactNode
  /**
   * Presentational loading flag. Renders a hardcoded-regular `CircleNotch`
   * spinner, forces `disabled`, sets `aria-busy="true"`, and disables motion.
   * This is the DUMB flag you flip yourself; for promise/async orchestration
   * reach for {@link StatefulButton}.
   *
   * @default false
   */
  isLoading?: boolean
  /**
   * Spinner side while `isLoading`. Replaces `startContent` (start) or
   * `endContent` (end); the opposite slot still renders its content. No-op when
   * `isLoading` is false.
   *
   * @default "start"
   */
  spinnerPlacement?: SpinnerPlacement
  /**
   * Convenience: square icon button. Maps the resolved `size` to its paired
   * icon size token for the cva call only (`xs→icon-xs`, `sm→icon-sm`,
   * `md→icon`, `lg→icon-lg`, `xl→icon-lg`). If an `icon*` size is already
   * passed, that wins. Icon-only buttons require an accessible name — pass
   * `aria-label` (dev-only warn otherwise). Ignored when `asChild`.
   *
   * @default false
   */
  isIconOnly?: boolean
}
```

**Example:**

```tsx
import { Button } from "@saasflare/ui";

<Button>Default</Button>
<Button variant="solid" intent="success">Save</Button>
<Button variant="outline" intent="danger" size="sm">Delete</Button>
<Button surface="glass">Inherits glass surface</Button>
<Button animated={false}>No motion</Button>
<Button variant="shadow">Elevated Shadow</Button>
<Button variant="ghost" size="icon"><MagnifyingGlassIcon /></Button>
```

---

## Button Group

**Description:** Visually connected strip of buttons with shared radii and separators. For segmented actions and toolbars.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/button-group.json
```

**Props:**

```ts
interface ButtonGroupProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    VariantProps<typeof buttonGroupVariants>,
    SaasflareComponentProps {}

/**
 * Groups multiple buttons or inputs into a visually connected strip with shared
 * border radii. The `radius` axis drives the corner rounding of the whole group;
 * connected edges between children have their adjacent corners flattened.
 *
 * @example
 * <ButtonGroup orientation="horizontal" radius="lg">
 *   <Button>Left</Button>
 *   <Button>Right</Button>
 * </ButtonGroup>
 */
function ButtonGroup({
  className,
  orientation = "horizontal",
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { ButtonGroup, ButtonGroupText } from '@saasflare/ui';
<ButtonGroup orientation="horizontal">
  <ButtonGroupText>Left</ButtonGroupText>
  <ButtonGroupText>Right</ButtonGroupText>
</ButtonGroup>
```

---

## Calendar

**Description:** Month-grid date calendar (react-day-picker) supporting single, multiple, or range selection.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/calendar.json
```

**Example:**

```tsx
import { Calendar } from '@saasflare/ui';
const [date, setDate] = React.useState<Date | undefined>(new Date());
<Calendar mode="single" selected={date} onSelect={setDate} />
```

---

## Callout

**Description:** Emphasized inline message box (info/warning/success/danger). Lives between Alert and Dialog.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/callout.json
```

**Props:**

```ts
export interface CalloutProps extends SaasflareComponentProps {
    /** Color intent. Default: `"info"`. */
    intent?: CalloutIntent
    /** Bold title rendered above the body. */
    title?: ReactNode
    /** Leading icon (rendered in the same color as the intent stripe). */
    icon?: ReactNode
    /** Body content. */
    children?: ReactNode
    /** Additional class names. */
    className?: string
}
```

**Example:**

```tsx
<Callout intent="warning" title="Heads up">
  This action is irreversible. Make sure you've exported your data first.
</Callout>
```

---

## Card

**Description:** The base surface primitive — header, content, and footer slots — that most composed cards build on.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/card.json
```

**Props:**

```ts
interface CardProps
  extends Omit<React.ComponentProps<"div">, MotionConflicts | keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Card container with subtle hover-lift animation.
 *
 * @component
 * @layer core
 *
 * @example
 * <Card className="max-w-sm">
 *   <CardHeader><CardTitle>Plan</CardTitle></CardHeader>
 *   <CardContent>Content here</CardContent>
 * </Card>
 */
function Card({ className, surface, radius, animated, iconWeight, ...props }: CardProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })
  const motion = useSaasflareMotion(sf.animated, springGentle)

  return (
    <m.div
      {...props}
      data-slot="card"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
      whileHover={
        motion.disabled
          ? undefined
          : { y: -2, boxShadow: "0 8px 30px color-mix(in oklab, var(--foreground) 8%, transparent)" }
      }
      transition={motion.transition}
      className={cn(
        "flex flex-col gap-6 rounded-xl border bg-card py-6 text-card-foreground shadow-sm transition-[border-color] duration-300 hover:border-primary/20",
        className
      )}
    />
  )
}
```

**Example:**

```tsx
import { Card, CardHeader, CardTitle, CardContent } from "@saasflare/ui";
<Card>
  <CardHeader>
    <CardTitle>Settings</CardTitle>
  </CardHeader>
  <CardContent>...</CardContent>
</Card>
```

---

## Carousel

**Description:** Touch/swipe carousel (Embla) with autoplay, looping, and custom controls for galleries and sliders.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/carousel.json
```

**Example:**

```tsx
import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext } from '@saasflare/ui/carousel';
<Carousel>
  <CarouselContent>
    <CarouselItem>Slide 1</CarouselItem>
    <CarouselItem>Slide 2</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

---

## Category Bar

**Description:** Segmented progress bar with per-segment colors and optional labels. Useful for resource breakdowns.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/category-bar.json
```

**Props:**

```ts
export interface CategoryBarProps extends SaasflareComponentProps {
    /** Segments to render, left-to-right. */
    segments: CategoryBarSegment[]
    /** Bar height in pixels. Default: `8`. */
    height?: number
    /** Render labels + percentages under each segment. */
    showLabels?: boolean
    /** Formats the percentage text. Default: `"NN%"`. */
    valueFormatter?: (percent: number) => string
    /** Additional class names. */
    className?: string
    /** Accessible label for the bar group. */
    "aria-label"?: string
}
```

**Example:**

```tsx
<CategoryBar
  segments={[
    { value: 30, color: "var(--chart-1)", label: "Images" },
    { value: 20, color: "var(--chart-2)", label: "Docs"   },
    { value: 50, color: "var(--chart-3)", label: "Other"  },
  ]}
  showLabels
/>
```

---

## Chart

**Description:** Composable Recharts wrapper with themed tooltips, legends, and design-system color tokens.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/chart.json
```

**Example:**

```tsx
import { ChartContainer, ChartTooltip, ChartTooltipContent } from '@saasflare/ui/chart';
const config = { revenue: { label: "Revenue", color: "var(--chart-1)" } };
<ChartContainer config={config}>
  <BarChart data={data}>
    <Bar dataKey="revenue" />
    <ChartTooltip content={<ChartTooltipContent />} />
  </BarChart>
</ChartContainer>
```

---

## Checkbox

**Description:** Accessible checkbox with indeterminate state, for forms and bulk-select rows.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/checkbox.json
```

**Props:**

```ts
interface CheckboxProps
  extends Omit<React.ComponentProps<typeof CheckboxPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Checkbox input with a bouncy spring check-mark animation. Built on the
 * Radix Checkbox primitive; supports controlled and uncontrolled checked
 * state. Pair with a `<label htmlFor>` for an accessible name.
 *
 * @component
 * @layer core
 *
 * @example
 * <Checkbox id="terms" />
 * <label htmlFor="terms">Accept terms and conditions</label>
 */
function Checkbox({
  className,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Checkbox } from "@saasflare/ui";

<Checkbox id="terms" />
<label htmlFor="terms">Accept terms and conditions</label>
```

---

## Code Block

**Description:** Code-block chrome: filename header, language badge, copy button, optional line numbers. BYO highlighter.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/code-block.json
```

**Props:**

```ts
export interface CodeBlockProps
    extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
        SaasflareComponentProps {
    /** Plain source code (rendered as monospace, no highlighting). */
    code?: string
    /**
     * Pre-highlighted HTML — e.g. output from Shiki's `codeToHtml`. Injected
     * verbatim via `dangerouslySetInnerHTML`, so it MUST be trusted,
     * server-generated markup. Never pass untrusted/user-supplied HTML.
     */
    highlighted?: string
    /** Language label shown in the header (purely cosmetic). */
    language?: string
    /** Filename shown left of the language badge. */
    filename?: string
    /**
     * Show 1-based line numbers in the gutter. Only applies to the plain
     * `code` path; when `highlighted` HTML is supplied it owns its own
     * rendering and this flag is ignored.
     */
    showLineNumbers?: boolean
    /** Hide the top bar (copy button still floats inside the block). */
    hideHeader?: boolean
    /** Hide the copy-to-clipboard button. */
    hideCopyButton?: boolean
}
```

**Example:**

```tsx
// Plain (no highlighting)
<CodeBlock code={`function hi() { return "hello" }`} language="ts" filename="hi.ts" />
```

---

## Collapsible

**Description:** Single show/hide region with animated open/close. The building block under accordions and disclosures.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/collapsible.json
```

**Example:**

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@saasflare/ui';
<Collapsible>
  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
  <CollapsibleContent>Hidden content revealed on toggle.</CollapsibleContent>
</Collapsible>
```

---

## Combobox

**Description:** Searchable select — a Popover wrapping a cmdk palette. Autocomplete with full keyboard navigation.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/combobox.json
```

**Example:**

```tsx
import {
  Combobox, ComboboxTrigger, ComboboxContent,
  ComboboxInput, ComboboxList, ComboboxItem,
} from "@saasflare/ui"

<Combobox>
  <ComboboxTrigger asChild>
    <Button variant="outline">{label ?? "Select…"}</Button>
  </ComboboxTrigger>
  <ComboboxContent>
    <ComboboxInput placeholder="Search…" />
    <ComboboxList>
      <ComboboxItem value="react">React</ComboboxItem>
      <ComboboxItem value="vue">Vue</ComboboxItem>
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

---

## Command

**Description:** ⌘K command palette with fuzzy search, groups, and keyboard navigation (cmdk).

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/command.json
```

**Props:**

```ts
interface CommandProps
  extends Omit<React.ComponentProps<typeof CommandPrimitive>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Command palette root — a searchable, keyboard-navigable command menu built on cmdk.
 *
 * Filters {@link CommandItem} children as the user types into {@link CommandInput}.
 * Resolves the design-system axes and emits them as data attributes. For a modal
 * ⌘K-style palette use {@link CommandDialog}.
 *
 * @component
 * @layer core
 */
function Command({
  className,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Command, CommandInput, CommandList, CommandItem, CommandGroup } from '@saasflare/ui';
<Command>
  <CommandInput placeholder="Search..." />
  <CommandList>
    <CommandGroup heading="Actions">
      <CommandItem>New File</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
```

---

## Compare

**Description:** Before/after image slider with a draggable divider, for comparisons and product demos.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/compare.json
```

**Props:**

```ts
export interface CompareProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Content shown on the left (before) side. */
  before: ReactNode
  /** Content shown on the right (after) side. */
  after: ReactNode
  /** Label for the before side. */
  beforeLabel?: string
  /** Label for the after side. */
  afterLabel?: string
  /** Initial divider position as percentage (0–100). Default: `50` */
  initialPosition?: number
  /** CSS aspect-ratio for the container. Default: `"16/9"` */
  aspectRatio?: string
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { Compare } from '@saasflare/ui';
<Compare
  before={<img src="/before.png" alt="Before" />}
  after={<img src="/after.png" alt="After" />}
/>
```

---

## Confetti

**Description:** CSS-only confetti burst with randomized colors and trajectories — celebrate conversions and milestones.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/confetti.json
```

**Props:**

```ts
export interface ConfettiProps extends SaasflareComponentProps {
  /** Whether the confetti burst is active. */
  active: boolean
  /** Number of confetti particles. Default: `40` */
  count?: number
  /** Array of CSS colors for particles. */
  colors?: string[]
  /** Duration in milliseconds before auto-cleanup. Default: `3000` */
  duration?: number
  /** Callback when animation completes. */
  onComplete?: () => void
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { Confetti } from '@saasflare/ui';
const [show, setShow] = useState(false);
<button onClick={() => setShow(true)}>Celebrate!</button>
<Confetti active={show} onComplete={() => setShow(false)} />
```

---

## Context Menu

**Description:** Right-click menu with items, submenus, checkboxes, and keyboard shortcuts.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/context-menu.json
```

**Example:**

```tsx
import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem } from '@saasflare/ui';
<ContextMenu>
  <ContextMenuTrigger>Right-click here</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>Copy</ContextMenuItem>
    <ContextMenuItem>Paste</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

---

## Countdown

**Description:** Presentational countdown display (days/hours/minutes/seconds) — pair with the useCountdown hook.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/countdown.json
```

**Props:**

```ts
export interface CountdownProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Number of days remaining. */
  days: number
  /** Number of hours remaining (0–23). */
  hours: number
  /** Number of minutes remaining (0–59). */
  minutes: number
  /** Number of seconds remaining (0–59). */
  seconds: number
  /** Show the labels below each box. Default: `true` */
  showLabels?: boolean
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { Countdown } from '@saasflare/ui';
import { useCountdown } from '@saasflare/ui';
const { days, hours, minutes, seconds } = useCountdown(targetDate);
<Countdown days={days} hours={hours} minutes={minutes} seconds={seconds} />
```

---

## Data Pagination

**Description:** Total-driven pagination control — prev/next, numbered pages with ellipsis, an optional page-size selector and an 'X–Y of N' summary. One component wires a whole table footer.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/data-pagination.json
```

**Props:**

```ts
export interface DataPaginationProps
  extends Omit<React.ComponentProps<"nav">, "onChange" | keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Total number of ITEMS across all pages. Used with `pageSize` to derive page count + the "X–Y of N" summary. Ignored if `pageCount` is set. */
  total?: number
  /** Precomputed total number of PAGES. Use when the backend returns a page count directly (no item total). Takes precedence over `total`/`pageSize`. */
  pageCount?: number
  /** Items per page. Required when using `total`; drives summary math + page-count derivation. Default: `10`. */
  pageSize?: number
  /** Controlled active page (1-indexed). When provided, the component is controlled and you MUST update it from `onPageChange`. */
  page?: number
  /** Initial page for uncontrolled mode. Default: `1`. Ignored when `page` is provided. */
  defaultPage?: number
  /** Fired with the next 1-indexed page when the user navigates. Always clamped to `[1, derivedPageCount]`. */
  onPageChange?: (page: number) => void
  /** Sibling pages shown each side of the active page (forwarded to {@link usePagination}). Default: `1`. */
  siblings?: number
  /** Boundary pages pinned at each end (forwarded to {@link usePagination}). Default: `1`. */
  boundaries?: number
  /** Show the prev/next caret controls. Default: `true`. */
  showControls?: boolean
  /** Show numbered page links + ellipsis. When `false`, renders only controls + summary (compact mode). Default: `true`. */
  showNumbers?: boolean
  /** Render the "X–Y of N" summary text. Auto-disabled (with a dev warning) when neither `total` nor an item count is known. Default: `false`. */
  showSummary?: boolean
  /** Render a page-size `<select>` built on {@link NativeSelect}. Requires `onPageSizeChange`. Default: `false`. */
  showPageSize?: boolean
  /** Selectable page sizes for the size selector. Default: `[10, 20, 50, 100]`. */
  pageSizeOptions?: readonly number[]
  /**
   * Fired with the chosen page size. The component does NOT internally manage
   * `pageSize` (controlled-only) — keeps a single source of truth with the
   * consumer. Changing `pageSize` does NOT auto-correct the active page when it
   * exceeds the new page count; reset the page yourself (e.g. `setPage(1)`).
   */
  onPageSizeChange?: (pageSize: number) => void
  /** Visual placement of summary/size-selector vs the page numbers. Default: `"split"` (summary left, numbers center, size right). */
  layout?: DataPaginationLayout
  /** Button-variant size token for prev/next + number links (forwarded to PaginationLink). Default: `"md"` (icon-square numbers + `md` controls). */
  size?: DataPaginationSize
  /** Accessible label for the nav landmark. Default: `"pagination"`. */
  "aria-label"?: string
  /** i18n / label overrides. */
  labels?: DataPaginationLabels
}
```

**Example:**

```tsx
import { DataPagination } from '@saasflare/ui';
<DataPagination total={248} pageSize={20} showSummary onPageChange={fetchPage} />
```

---

## Data Table

**Description:** Dependency-free data grid built on the Table primitives — typed columns, client-side sort, row selection, and pagination out of the box, with a server-side/TanStack escape hatch.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/data-table.json
```

**Props:**

```ts
interface DataTableProps<T>
  extends Omit<React.ComponentProps<"table">, "children" | keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Row data. */
  data: T[]
  /** Typed column definitions. */
  columns: DataTableColumn<T>[]
  /** Stable row key. String key of `T` or a function. Falls back to row index (logs a dev warning, since index keys break selection across sort/paginate). */
  getRowId?: keyof T | ((row: T, index: number) => string)

  // ── Sorting (multi-column, asc → desc → none cycle) ───────────────────────
  /** Uncontrolled initial sort. */
  defaultSort?: DataTableSort[]
  /** Controlled sort state. Presence switches sorting to controlled. */
  sort?: DataTableSort[]
  /** Fires on header activation with the next sort array. */
  onSortChange?: (sort: DataTableSort[]) => void
  /** Allow stacking multiple sort columns (shift-click adds a column). Default `false` (single-column). */
  multiSort?: boolean
  /** Skip internal sorting (server/TanStack drives order). Header still emits `onSortChange`. Default `false`. */
  manualSort?: boolean

  // ── Selection (header + per-row checkbox) ─────────────────────────────────
  /** `"none"` (default) | `"single"` | `"multiple"`. Renders a leading checkbox column when not `"none"`. */
  selectionMode?: DataTableSelectionMode
  /** Uncontrolled initial selected row-id set. */
  defaultSelectedKeys?: string[]
  /** Controlled selected row-id set. */
  selectedKeys?: string[]
  /** Fires with the next selected row-id array. */
  onSelectedKeysChange?: (keys: string[]) => void
  /** Predicate to disable selection for specific rows (their checkbox is disabled + excluded from select-all). */
  isRowSelectable?: (row: T) => boolean

  // ── Pagination (reuses usePagination) ─────────────────────────────────────
  /** Rows per page. Omit / `0` disables pagination (renders all rows, no footer). */
  pageSize?: number
  /** Uncontrolled initial page (1-indexed). Default `1`. */
  defaultPage?: number
  /** Controlled page (1-indexed). */
  page?: number
  /** Fires on page change. */
  onPageChange?: (page: number) => void
  /** Skip internal pagination/slicing (server drives the window). `data` is treated as the current page; pass `rowCount` for the footer. Default `false`. */
  manualPagination?: boolean
  /** Total row count when `manualPagination` — drives the page-count math in the footer. */
  rowCount?: number

  // ── States / chrome ───────────────────────────────────────────────────────
  /** Loading flag — renders `loadingRows` skeleton rows; disables sort/select while true. */
  loading?: boolean
  /** Skeleton row count while `loading`. Default = `pageSize || 5`. */
  loadingRows?: number
  /** Rendered in a full-width body row when `data` is empty and not loading. Defaults to a built-in message. */
  emptyState?: React.ReactNode
  /** Pin the header on vertical scroll within a `maxHeight` container. Default `false`. */
  stickyHeader?: boolean
  /** Max body height (enables internal scroll; required for `stickyHeader` to be useful). e.g. `"24rem"`. */
  maxHeight?: number | string
  /** Density preset. Default `"comfortable"`. */
  density?: DataTableDensity
  /** Optional row click handler. Receives row + index. Adds `cursor-pointer` + keyboard activation when set. */
  onRowClick?: (row: T, index: number) => void
  /** Accessible caption (visually hidden by default) describing the table. */
  caption?: React.ReactNode
  /** Hide the built-in pagination footer even when paginated (consumer renders own Pagination). Default `false`. */
  hidePagination?: boolean
}
```

**Example:**

```tsx
import { DataTable } from "@saasflare/ui";
<DataTable
  data={users}
  columns={[
    { accessorKey: "name", header: "Name", sortable: true },
    { accessorKey: "email", header: "Email" },
  ]}
  getRowId="id"
  selectionMode="multiple"
  pageSize={10}
/>
```

---

## Data Toolbar

**Description:** Toolbar layout for tables and data grids — search, filters, and actions in a single bar.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/data-toolbar.json
```

**Props:**

```ts
interface DataToolbarProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/** Props for {@link DataToolbarSearch}. */
interface DataToolbarSearchProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/** Props for {@link DataToolbarFilters}. */
interface DataToolbarFiltersProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/** Props for {@link DataToolbarActions}. */
interface DataToolbarActionsProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/**
 * Toolbar container for data views.
 *
 * @component
 * @layer core
 *
 * @example
 * <DataToolbar>
 *   <DataToolbarSearch placeholder="Search..." />
 *   <DataToolbarActions>
 *     <Button size="sm">Add New</Button>
 *   </DataToolbarActions>
 * </DataToolbar>
 */
function DataToolbar({ className, surface, radius, animated, iconWeight, ...props }: DataToolbarProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })

  return (
    <div
      {...props}
      data-slot="data-toolbar"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
      className={cn(
        "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between",
        className
      )}
    />
  )
}
```

**Example:**

```tsx
import { DataToolbar, DataToolbarSearch, DataToolbarActions, DataToolbarFilters } from "@saasflare/ui";

<DataToolbar>
  <DataToolbarSearch placeholder="Search users..." />
  <DataToolbarFilters>
    <Select>...</Select>
  </DataToolbarFilters>
  <DataToolbarActions>
    <Button size="sm">Export</Button>
  </DataToolbarActions>
</DataToolbar>
```

---

## Date Picker

**Description:** Controlled/uncontrolled single-date input — Button + Popover + single-mode Calendar.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/date-picker.json
```

**Props:**

```ts
export interface DatePickerProps extends SaasflareComponentProps {
    /** Controlled value. Pass `null` for a controlled-but-empty picker. */
    value?: Date | null
    /** Uncontrolled default value. */
    defaultValue?: Date
    /** Called when the user picks a date (`undefined` on deselect — writing it back to state keeps the picker controlled and clears it). */
    onChange?: (date: Date | undefined) => void
    /** Placeholder shown when no date is set. */
    placeholder?: string
    /** Earliest pickable date. */
    minDate?: Date
    /** Latest pickable date. */
    maxDate?: Date
    /** Disable the trigger. */
    disabled?: boolean
    /** Format function for the trigger label. Default: locale-aware. */
    formatDate?: (date: Date) => string
    /** Additional class names on the trigger. */
    className?: string
}
```

**Example:**

```tsx
const [date, setDate] = useState<Date | undefined>();
<DatePicker value={date} onChange={setDate} />
```

---

## Date Range Picker

**Description:** Controlled/uncontrolled date-range input — Button + Popover + range-mode Calendar.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/date-range-picker.json
```

**Props:**

```ts
export interface DateRangePickerProps extends SaasflareComponentProps {
    /** Controlled value. Pass `null` for a controlled-but-empty picker. */
    value?: DateRange | null
    /** Uncontrolled default value. */
    defaultValue?: DateRange
    /** Called when the user picks a new range (`undefined` on deselect — writing it back to state keeps the picker controlled and clears it). */
    onChange?: (range: DateRange | undefined) => void
    /** Placeholder shown in the trigger when no range is set. */
    placeholder?: string
    /** Number of months shown side-by-side. Default: `2`. */
    numberOfMonths?: number
    /** Earliest pickable date. */
    minDate?: Date
    /** Latest pickable date. */
    maxDate?: Date
    /** Disable the trigger. */
    disabled?: boolean
    /** Format function for the trigger label. Default: locale-aware `toLocaleDateString`. */
    formatRange?: (range: DateRange) => string
    /** Additional class names on the trigger. */
    className?: string
}
```

**Example:**

```tsx
const [range, setRange] = useState<DateRange | undefined>();
<DateRangePicker value={range} onChange={setRange} />
```

---

## Device Mock

**Description:** CSS-only phone, laptop, and browser frames for wrapping product screenshots and demos.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/device-mock.json
```

**Example:**

```tsx
import { SafariMock, IPhoneMock } from '@saasflare/ui';
<SafariMock url="https://app.example.com">
  <img src="/screenshot.png" alt="App screenshot" />
</SafariMock>
```

---

## Dialog

**Description:** Modal overlay for focused tasks and forms, with animated enter/exit and focus trapping.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/dialog.json
```

**Example:**

```tsx
import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle } from "@saasflare/ui";
<Dialog>
  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
  <DialogContent>
    <DialogHeader><DialogTitle>Edit Profile</DialogTitle></DialogHeader>
  </DialogContent>
</Dialog>
```

---

## Dock

**Description:** macOS-style dock bar where icons magnify on cursor proximity. Playful navigation accent.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/dock.json
```

**Props:**

```ts
export interface DockProps extends SaasflareComponentProps {
  /** Dock items. */
  children: ReactNode
  /** Maximum scale factor for magnified items. Default: `1.5` */
  magnification?: number
  /** Mouse proximity distance in pixels that triggers magnification. Default: `100` */
  distance?: number
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { Dock, DockItem } from '@saasflare/ui';
<Dock>
  <DockItem label="Home"><HomeIcon className="size-6" /></DockItem>
  <DockItem label="Search"><SearchIcon className="size-6" /></DockItem>
  <DockItem label="Settings"><SettingsIcon className="size-6" /></DockItem>
</Dock>
```

---

## Drawer

**Description:** Mobile-first bottom drawer with drag-to-dismiss physics (Vaul). The touch-friendly Sheet.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/drawer.json
```

**Example:**

```tsx
import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle } from "@saasflare/ui";

<Drawer>
  <DrawerTrigger asChild><Button>Open Drawer</Button></DrawerTrigger>
  <DrawerContent>
    <DrawerHeader><DrawerTitle>Settings</DrawerTitle></DrawerHeader>
  </DrawerContent>
</Drawer>
```

---

## Dropdown Menu

**Description:** Click-triggered action menu with items, submenus, checkboxes, radio groups, and shortcuts.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/dropdown-menu.json
```

**Example:**

```tsx
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@saasflare/ui';

<DropdownMenu>
  <DropdownMenuTrigger>Open</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Profile</DropdownMenuItem>
    <DropdownMenuItem>Settings</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

---

## Dropzone

**Description:** Drag-and-drop file upload area with click-to-open fallback. Self-contained (no react-dropzone).

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/dropzone.json
```

**Props:**

```ts
export interface DropzoneProps extends SaasflareComponentProps {
    /** Called with `(accepted, rejected)` when the user drops or picks files. */
    onDrop?: (accepted: File[], rejected: DropzoneRejection[]) => void
    /** MIME types or extensions to accept (matches `<input accept>`). */
    accept?: string
    /** Maximum file size in bytes. */
    maxSize?: number
    /** Allow multiple file selection. Default: `true`. */
    multiple?: boolean
    /** Disable the dropzone. */
    disabled?: boolean
    /** Render-prop body. Receives `isDragActive`. Falls back to the default UI. */
    children?: ReactNode | ((state: { isDragActive: boolean }) => ReactNode)
    /** Additional class names. */
    className?: string
}
```

**Example:**

```tsx
<Dropzone
  accept="image/*"
  maxSize={5 * 1024 * 1024}
  onDrop={(accepted, rejected) => upload(accepted)}
/>
```

---

## Empty

**Description:** Empty-state primitive — centered icon, title, description, and action slots for zero-data views.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/empty.json
```

**Props:**

```ts
interface EmptyProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/**
 * Empty-state placeholder — a dashed-border container centered in its parent.
 * Use when a list, table, or search has nothing to show; compose with
 * {@link EmptyHeader}, {@link EmptyTitle}, {@link EmptyDescription}, and
 * {@link EmptyContent}.
 *
 * @component
 * @layer core
 *
 * @example
 * <Empty>
 *   <EmptyHeader>
 *     <EmptyTitle>No items found</EmptyTitle>
 *     <EmptyDescription>Try adjusting your filters.</EmptyDescription>
 *   </EmptyHeader>
 *   <EmptyContent>Create one</EmptyContent>
 * </Empty>
 */
function Empty({ className, surface, radius, animated, iconWeight, ...props }: EmptyProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })

  return (
    <div
      {...props}
      data-slot="empty"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
      className={cn(
        "flex min-w-0 flex-1 flex-col items-center justify-center gap-6 rounded-lg border-dashed p-6 text-center text-balance md:p-12",
        className
      )}
    />
  )
}
```

**Example:**

```tsx
import { Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent } from '@saasflare/ui';
<Empty>
  <EmptyHeader>
    <EmptyTitle>No items found</EmptyTitle>
    <EmptyDescription>Try adjusting your filters.</EmptyDescription>
  </EmptyHeader>
  <EmptyContent>Create one</EmptyContent>
</Empty>
```

---

## Empty State

**Description:** Polished zero-data view — icon or illustration, title, description, and a call-to-action button.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/empty-state.json
```

**Props:**

```ts
interface EmptyStateProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
  /**
   * Icon or illustration element. Rendered verbatim — because this is an
   * arbitrary `ReactNode` rather than an internal Phosphor icon, the
   * provider's `iconWeight` does not reach it. Set `weight` on the icon
   * you pass (e.g. `<InboxIcon weight="duotone" />`) for weight control.
   */
  icon?: React.ReactNode
  /** Title text */
  title: string
  /** Description text */
  description?: string
  /** Action element (button, link, etc.) */
  action?: React.ReactNode
}
```

**Example:**

```tsx
import { EmptyState } from "@saasflare/ui";
import { InboxIcon } from "./phosphor";

<EmptyState
  icon={<InboxIcon />}
  title="No messages"
  description="You haven't received any messages yet."
  action={<Button>Compose</Button>}
/>
```

---

## Feature Card

**Description:** Feature card with icon, title, and description. The most reused card pattern on any SaaS landing page.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/feature-card.json
```

**Props:**

```ts
export interface FeatureCardProps extends SaasflareComponentProps {
  /** Icon element displayed at the top. */
  icon?: ReactNode
  /** Feature title. */
  title: string
  /** Feature description text. */
  description: string
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { FeatureCard } from '@saasflare/ui';
<FeatureCard
  icon={<ZapIcon />}
  title="Lightning Fast"
  description="Deploy in under 30 seconds with zero configuration."
/>
```

---

## Field

**Description:** Form-field wrapper bundling label, control, description, and error message with correct a11y wiring.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/field.json
```

**Props:**

```ts
interface FieldProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    VariantProps<typeof fieldVariants>,
    SaasflareComponentProps {}

/**
 * Structured form field root — lays out a label, control, description and error
 * with consistent spacing. Honors the Saasflare theme axes (surface, radius,
 * animated) so nested selectable fields adopt the active design tokens.
 *
 * @component
 * @layer core
 *
 * @example
 * <Field orientation="horizontal">
 *   <FieldLabel>Notifications</FieldLabel>
 *   <FieldDescription>Receive product updates</FieldDescription>
 * </Field>
 */
function Field({
  className,
  orientation = "vertical",
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Field, FieldLabel, FieldError } from '@saasflare/ui';
<Field>
  <FieldLabel>Email</FieldLabel>
  <input type="email" />
  <FieldError>Required</FieldError>
</Field>
```

---

## Flip Words

**Description:** Cycles through a list of words with a vertical flip animation — for dynamic hero headlines.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/flip-words.json
```

**Props:**

```ts
export interface FlipWordsProps
  extends Omit<React.ComponentProps<"span">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Array of words to cycle through. */
  words: string[]
  /** Cycle interval in milliseconds. Default: `2500` */
  interval?: number
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { FlipWords } from '@saasflare/ui';
<h1>
  Build <FlipWords words={["websites", "apps", "products"]} /> faster
</h1>
```

---

## Form

**Description:** react-hook-form integration layer — field context, labels, descriptions, and validation messages.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/form.json
```

**Example:**

```tsx
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from '@saasflare/ui';
<Form {...form}>
  <FormField control={form.control} name="email" render={({ field }) => (
    <FormItem>
      <FormLabel>Email</FormLabel>
      <FormControl><input {...field} /></FormControl>
      <FormMessage />
    </FormItem>
  )} />
</Form>
```

---

## Gallery Lightbox

**Description:** Click-to-expand image gallery with a fullscreen overlay, prev/next, and keyboard navigation.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/gallery-lightbox.json
```

**Props:**

```ts
export interface GalleryLightboxProps extends SaasflareComponentProps {
  /** Array of image URLs. */
  images: string[]
  /** Whether the lightbox is open. */
  open: boolean
  /** Current image index. */
  index: number
  /** Called when the lightbox should close. */
  onClose: () => void
  /** Called when the index changes. */
  onIndexChange: (index: number) => void
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { GalleryLightbox } from '@saasflare/ui';
const [open, setOpen] = useState(false);
const [index, setIndex] = useState(0);
<GalleryLightbox
  images={["/img1.jpg", "/img2.jpg", "/img3.jpg"]}
  open={open}
  index={index}
  onClose={() => setOpen(false)}
  onIndexChange={setIndex}
/>
```

---

## Glowing Effect

**Description:** Mouse-tracking glow that follows the cursor around a container's edges. Interactive card highlight.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/glowing-effect.json
```

**Props:**

```ts
export interface GlowingEffectProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Glow color. Default: `"var(--primary)"` */
  color?: string
  /** Glow spread diameter in pixels. Default: `150` */
  spread?: number
  /** Blur radius in pixels. Default: `20` */
  blur?: number
  /** Glow opacity (0–1). Default: `0.4` */
  opacity?: number
  /** Border radius to match parent (CSS value). Default: `"inherit"` */
  borderRadius?: string
}
```

**Example:**

```tsx
import { GlowingEffect } from '@saasflare/ui';
<div className="relative overflow-hidden rounded-xl border p-6">
  <GlowingEffect />
  <h3>Feature Card</h3>
</div>
```

---

## Gradient Text

**Description:** Animated linear-gradient text fill via background-clip — for headlines and brand accents.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/gradient-text.json
```

**Props:**

```ts
export interface GradientTextProps
  extends Omit<React.ComponentProps<"span">, keyof SaasflareComponentProps | "color">,
    SaasflareComponentProps {
  /** Text content to apply the gradient to. */
  children: ReactNode
  /** Gradient color stops. Default: `--primary` → `--chart-1` → `--chart-2` design tokens (OKLCH). */
  colors?: string[]
  /**
   * Per-instance toggle for the gradient-position animation. Default: `true`.
   * Layered on top of the design-system `animated` axis — the gradient only
   * shifts when both this and the resolved `animated` flag are enabled.
   */
  animate?: boolean
  /** Animation cycle duration in seconds. Default: `6` */
  speed?: number
  /** Gradient direction in degrees. Default: `90` */
  angle?: number
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { GradientText } from '@saasflare/ui';
<h1>
  Build with <GradientText>Saasflare</GradientText>
</h1>
```

---

## Hero Video Dialog

**Description:** Poster image with a play button that opens an embedded video in a modal. Landing-page hero staple.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/hero-video-dialog.json
```

**Props:**

```ts
export interface HeroVideoDialogProps
  extends Omit<React.ComponentProps<"button">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Video embed URL (YouTube/Vimeo embed or direct video URL). */
  videoSrc: string
  /** Poster thumbnail image URL. */
  thumbnailSrc: string
  /** Alt text for the thumbnail image. */
  thumbnailAlt: string
  /** CSS aspect-ratio for the thumbnail. Default: `"16/9"` */
  aspectRatio?: string
}
```

**Example:**

```tsx
import { HeroVideoDialog } from '@saasflare/ui';
<HeroVideoDialog
  videoSrc="https://www.youtube.com/embed/dQw4w9WgXcQ"
  thumbnailSrc="/product-demo-poster.jpg"
  thumbnailAlt="Product demo video"
/>
```

---

## Hotspot

**Description:** Pulsing marker dots at absolute positions with hover tooltips — annotate screenshots and demos.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/hotspot.json
```

**Props:**

```ts
export interface HotspotProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Background content (image, illustration, etc.) plus HotspotMarker children. */
  children: ReactNode
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { Hotspot, HotspotMarker } from '@saasflare/ui';
<Hotspot>
  <img src="/product.png" alt="Product" />
  <HotspotMarker x={30} y={45} label="Dashboard" />
  <HotspotMarker x={70} y={60} label="Analytics" />
</Hotspot>
```

---

## Hover Card

**Description:** Rich preview popover that opens on hover — user cards, link previews, and definitions.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/hover-card.json
```

**Example:**

```tsx
import { HoverCard, HoverCardTrigger, HoverCardContent } from '@saasflare/ui';

<HoverCard>
  <HoverCardTrigger>Hover me</HoverCardTrigger>
  <HoverCardContent>
    <p>Preview content appears here.</p>
  </HoverCardContent>
</HoverCard>
```

---

## Image Swap Hover

**Description:** Crossfades between a primary and alternate image on hover. Product and team-photo flourish.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/image-swap-hover.json
```

**Props:**

```ts
export interface ImageSwapHoverProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Default image source. */
  src: string
  /** Image source to show on hover. */
  hoverSrc: string
  /** Alt text for both images. */
  alt: string
  /** CSS aspect-ratio. Default: `"1/1"` */
  aspectRatio?: string
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { ImageSwapHover } from '@saasflare/ui';
<ImageSwapHover
  src="/product-front.jpg"
  hoverSrc="/product-back.jpg"
  alt="Product view"
/>
```

---

## Input

**Description:** Single-line text field — the form workhorse — with intent states and full sizing support.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/input.json
```

**Props:**

```ts
interface InputProps extends Omit<InputBaseProps, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/**
 * Single-line text input with a spring-animated focus ring. Accepts all
 * native input props; `surface`, `radius`, and `animated` resolve against
 * the <SaasflareProvider> context when omitted.
 *
 * @component
 * @layer core
 */
function Input({ className, type, surface, radius, animated, iconWeight, ...props }: InputProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })
  const motion = useSaasflareMotion(sf.animated, { type: "spring", stiffness: 300, damping: 20 })

  return (
    <m.input
      {...props}
      type={type}
      data-slot="input"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
      whileFocus={motion.disabled ? undefined : { boxShadow: "0 0 0 3px color-mix(in oklab, var(--ring) 30%, transparent)" }}
      transition={motion.transition}
      className={cn(
        "h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-xs transition-[color,border-color] outline-none selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:bg-input/30",
        "focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50",
        "aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40",
        className
      )}
    />
  )
}
```

**Example:**

```tsx
import { Input } from '@saasflare/ui';

<Input type="email" placeholder="you@example.com" />
```

---

## Input Group

**Description:** Wraps an input with addons, icons, and prefix/suffix elements into a single bordered unit.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/input-group.json
```

**Props:**

```ts
interface InputGroupProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * InputGroup — bordered container that visually unifies an input with inline
 * addons, buttons, and prefix/suffix text. Owns the focus ring, error styling,
 * and the theme axes (surface/radius/animated) for the whole group.
 *
 * @component
 * @example
 * <InputGroup>
 *   <InputGroupAddon>$</InputGroupAddon>
 *   <InputGroupInput placeholder="Amount" />
 * </InputGroup>
 */
function InputGroup({ className, surface, radius, animated, iconWeight, ...props }: InputGroupProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })
  return (
    <div
      data-slot="input-group"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
      role="group"
      className={cn(
        "group/input-group relative flex w-full items-center rounded-md border border-input shadow-xs transition-[color,box-shadow] outline-none dark:bg-input/30",
        "h-9 min-w-0 has-[>textarea]:h-auto",

        // Variants based on alignment.
        "has-[>[data-align=inline-start]]:[&>input]:pl-2",
        "has-[>[data-align=inline-end]]:[&>input]:pr-2",
        "has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-start]]:[&>input]:pb-3",
        "has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3",

        // Focus state.
        "has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-[3px] has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50",

        // Error state.
        "has-[[data-slot][aria-invalid=true]]:border-destructive has-[[data-slot][aria-invalid=true]]:ring-destructive/20 dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40",

        className
      )}
      {...props}
    />
  )
}
```

**Example:**

```tsx
import { InputGroup, InputGroupInput, InputGroupAddon } from '@saasflare/ui';
<InputGroup>
  <InputGroupAddon>$</InputGroupAddon>
  <InputGroupInput placeholder="Amount" />
</InputGroup>
```

---

## Input OTP

**Description:** One-time-code input with per-digit slots, paste handling, and auto-advance.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/input-otp.json
```

**Example:**

```tsx
import { InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator } from '@saasflare/ui';
<InputOTP maxLength={6}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
  </InputOTPGroup>
  <InputOTPSeparator />
  <InputOTPGroup>
    <InputOTPSlot index={3} />
    <InputOTPSlot index={4} />
    <InputOTPSlot index={5} />
  </InputOTPGroup>
</InputOTP>
```

---

## Item

**Description:** Generic list/row primitive with leading media, title, description, and trailing action slots.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/item.json
```

**Props:**

```ts
interface ItemProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    Omit<VariantProps<typeof itemVariants>, "size">,
    SaasflareComponentProps {
  /** Render as child element (Radix Slot pattern). */
  asChild?: boolean
  /** Row density. (`"default"` is a deprecated alias for `"md"`.) */
  size?: VariantProps<typeof itemVariants>["size"] | "default"
}
```

**Example:**

```tsx
import { ItemGroup, Item, ItemContent, ItemTitle } from '@saasflare/ui';

<ItemGroup>
  <Item>
    <ItemContent>
      <ItemTitle>Settings</ItemTitle>
    </ItemContent>
  </Item>
</ItemGroup>
```

---

## Kbd

**Description:** Inline keyboard-key styling for documenting shortcuts (⌘K, Ctrl+C).

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/kbd.json
```

**Props:**

```ts
interface KbdProps extends Omit<React.ComponentProps<"kbd">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/**
 * Renders a single keyboard key as a styled `<kbd>` element. Use it in
 * tooltips, menus, and docs to surface keyboard shortcuts.
 *
 * @component
 * @layer core
 */
function Kbd({ className, surface, radius, animated, iconWeight, ...props }: KbdProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })

  return (
    <kbd
      {...props}
      data-slot="kbd"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
      className={cn(
        "pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-sm bg-muted px-1 font-sans text-xs font-medium text-muted-foreground select-none",
        "[&_svg:not([class*='size-'])]:size-3",
        "[[data-slot=tooltip-content]_&]:bg-background/20 [[data-slot=tooltip-content]_&]:text-background dark:[[data-slot=tooltip-content]_&]:bg-background/10",
        className
      )}
    />
  )
}
```

**Example:**

```tsx
import { Kbd, KbdGroup } from '@saasflare/ui';
<KbdGroup><Kbd>Ctrl</Kbd><Kbd>S</Kbd></KbdGroup>
```

---

## Label

**Description:** Accessible form label wired to its control, with required and disabled styling.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/label.json
```

**Props:**

```ts
interface LabelProps
  extends Omit<React.ComponentProps<typeof LabelPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Accessible form label built on the Radix Label primitive. Dims itself when
 * the associated peer control or `data-disabled` group is disabled; associate
 * with a control via `htmlFor`.
 *
 * @component
 * @layer core
 *
 * @example
 * <Label htmlFor="email">Email address</Label>
 */
function Label({
  className,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Label } from '@saasflare/ui';
<Label htmlFor="email">Email address</Label>
```

---

## Marquee

**Description:** Infinite-scrolling row of content (logos, testimonials) — pure CSS, no animation frames.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/marquee.json
```

**Props:**

```ts
export interface MarqueeProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps | "children">,
    SaasflareComponentProps {
  /** Items to scroll infinitely. */
  children: ReactNode
  /** Reverse scroll direction. Default: `false` */
  reverse?: boolean
  /** Scroll duration in seconds for one full cycle. Default: `40` */
  speed?: number
  /** Pause scrolling on hover. Default: `true` */
  pauseOnHover?: boolean
  /** Gap between items in pixels. Default: `48` */
  gap?: number
  /** Number of times to duplicate the content strip. Default: `2` */
  repeat?: number
  /** Enable vertical scrolling instead of horizontal. Default: `false` */
  vertical?: boolean
  /** Additional class names for the container. */
  className?: string
}
```

**Example:**

```tsx
import { Marquee } from '@saasflare/ui';
<Marquee>
  <img src="/logo1.svg" alt="Logo 1" />
  <img src="/logo2.svg" alt="Logo 2" />
  <img src="/logo3.svg" alt="Logo 3" />
</Marquee>
```

---

## Menubar

**Description:** Desktop-style horizontal menu bar (File / Edit / View) with dropdowns and keyboard navigation.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/menubar.json
```

**Props:**

```ts
interface MenubarProps
  extends Omit<React.ComponentProps<typeof MenubarPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Root horizontal menu bar. Owns the Saasflare surface/radius/animated context for
 * its menus and emits the corresponding data attributes.
 */
function Menubar({
  className,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem } from '@saasflare/ui';
<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>New</MenubarItem>
      <MenubarItem>Open</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

---

## Metric Card

**Description:** Dashboard metric card with sparkline support and trend indicator.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/metric-card.json
```

**Props:**

```ts
interface MetricCardProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
  /** Metric label (e.g. "Revenue", "Active Users") */
  label: string
  /** Formatted metric value (e.g. "$12,345", "1,234") */
  value: string
  /** Optional trend indicator */
  trend?: MetricTrend
  /** Optional icon element */
  icon?: React.ReactNode
}
```

**Example:**

```tsx
import { MetricCard } from "@saasflare/ui";
import { UsersIcon } from "./phosphor";

<MetricCard
  label="Active Users"
  value="1,234"
  trend={{ value: 12.5, direction: "up" }}
  icon={<UsersIcon />}
/>
```

---

## Multi Select

**Description:** Searchable multi-select with chips, select-all, a max limit, and async option loading — built on Popover + cmdk, with a plain string[] value.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/multi-select.json
```

**Props:**

```ts
export interface MultiSelectProps
  extends Omit<React.ComponentProps<"div">, MultiSelectDomConflicts | keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Options to choose from. Update this array (+ `loading`) for async loading. */
  options: MultiSelectOption[]
  /** Controlled selected values (array of `option.value`). */
  value?: string[]
  /** Uncontrolled initial selection. @default [] */
  defaultValue?: string[]
  /** Fires on every selection change with the next value array. */
  onValueChange?: (value: string[]) => void
  /** Trigger placeholder when nothing is selected. @default "Select…" */
  placeholder?: string
  /** Search input placeholder. @default "Search…" */
  searchPlaceholder?: string
  /** Node shown when the query matches no option. @default "No results." */
  emptyMessage?: React.ReactNode
  /** Max number of selectable values. Over-limit options become non-interactive (data-disabled) and a "Max N selected" hint shows. */
  max?: number
  /** Show a clear-all (×) affordance on the trigger when selection is non-empty. @default true */
  clearable?: boolean
  /** Show a "Select all / Clear" header row (operates on the CURRENTLY FILTERED, non-disabled options). @default false */
  selectAll?: boolean
  /** Label for the select-all row. @default "Select all" */
  selectAllLabel?: string
  /** Close the popover after each pick. @default false (multi-pick stays open) */
  closeOnSelect?: boolean
  /** Max chip ROWS shown collapsed on the trigger before overflowing to "+N more" (HeroUI isMultiline analog). @default 1 */
  maxRows?: number
  /** Async: render a spinner row + aria-busy; pair with `onSearchChange` for server filtering. @default false */
  loading?: boolean
  /** Controlled search query (optional). */
  searchValue?: string
  /** Fires on query change. PRESENCE of this prop flips cmdk to `shouldFilter={false}` (server-side filtering); omit it for built-in client fuzzy search. */
  onSearchChange?: (query: string) => void
  /** Disable the whole control. */
  disabled?: boolean
  /** Forwarded to the cmdk list for ARIA. */
  "aria-label"?: string
  /** className on the trigger button (root data-axes div wraps it). */
  className?: string
  /** className on the popover content. */
  contentClassName?: string
}
```

**Example:**

```tsx
import { MultiSelect, type MultiSelectOption } from "@saasflare/ui"

const options: MultiSelectOption[] = [
  { value: "react", label: "React" },
  { value: "vue", label: "Vue" },
  { value: "svelte", label: "Svelte" },
]

const [value, setValue] = React.useState<string[]>([])
<MultiSelect options={options} value={value} onValueChange={setValue} />
```

---

## Mouse Gradient Blob

**Description:** Large blurred gradient blob that trails the cursor with spring physics. Ambient hero background.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/mouse-gradient-blob.json
```

**Props:**

```ts
export interface MouseGradientBlobProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Diameter of the blob in pixels. Default: `500` */
  size?: number
  /** Gradient color stops. Default: primary + chart-2 tokens */
  colors?: [string, string]
  /** Opacity of the blob (0–1). Default: `0.15` */
  opacity?: number
  /** Blur radius in pixels. Default: `80` */
  blur?: number
  /** Additional class names for the container */
  className?: string
}
```

**Example:**

```tsx
import { MouseGradientBlob } from '@saasflare/ui';
<div className="relative overflow-hidden">
  <MouseGradientBlob />
  <h1>Your content here</h1>
</div>
```

---

## Moving Border

**Description:** Continuously rotating conic-gradient border around an element. Eye-catching CTA wrapper.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/moving-border.json
```

**Props:**

```ts
export interface MovingBorderProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Content inside the border. */
  children: ReactNode
  /** Gradient colors for the rotating border. */
  colors?: string[]
  /** Rotation cycle duration in seconds. Default: `6` */
  duration?: number
  /** Border width in pixels. Default: `1.5` */
  borderWidth?: number
  /** Border radius (CSS value). Default: `"0.75rem"` */
  borderRadius?: string
  /** Additional class names for the outer wrapper. */
  className?: string
}
```

**Example:**

```tsx
import { MovingBorder } from '@saasflare/ui';
<MovingBorder>
  <button className="px-6 py-3 font-semibold">Get Started</button>
</MovingBorder>
```

---

## Native Select

**Description:** Lightweight native select with a chevron overlay — zero-JS dropdown for simple option lists.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/native-select.json
```

**Props:**

```ts
interface NativeSelectProps
  extends Omit<React.ComponentProps<"select">, "size" | keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Control height. `"sm"` renders a more compact trigger; `"md"` is the standard height. (`"default"` is a deprecated alias for `"md"`.) */
  size?: "sm" | "md" | "default"
}
```

**Example:**

```tsx
import { NativeSelect, NativeSelectOption } from '@saasflare/ui';
<NativeSelect>
  <NativeSelectOption value="a">Option A</NativeSelectOption>
  <NativeSelectOption value="b">Option B</NativeSelectOption>
</NativeSelect>
```

---

## Navigation Menu

**Description:** Top-level site navigation with animated mega-menu dropdowns and active-link states.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/navigation-menu.json
```

**Props:**

```ts
interface NavigationMenuProps
  extends Omit<React.ComponentProps<typeof NavigationMenuPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /**
   * Render the shared viewport panel for dropdown content.
   *
   * @default true
   */
  viewport?: boolean
}
```

**Example:**

```tsx
import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink } from '@saasflare/ui';
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/docs">Documentation</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

---

## Notification Center

**Description:** Bell-icon trigger + dropdown inbox with per-item read/dismiss controls. Composes Button + Popover + Badge.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/notification-center.json
```

**Props:**

```ts
export interface NotificationCenterProps extends SaasflareComponentProps {
    /** Notifications to display. */
    items: NotificationItem[]
    /** Header title in the popover. Default: `"Notifications"`. */
    title?: string
    /** Called when the user clicks a row (also passes the item). */
    onItemClick?: (item: NotificationItem) => void
    /** Called when "Mark as read" is tapped on a row. */
    onMarkRead?: (id: string) => void
    /** Called when "Mark all as read" is tapped. Hide the action by omitting this. */
    onMarkAllRead?: () => void
    /** Custom empty-state content. */
    emptyState?: ReactNode
    /** Maximum items rendered (older ones truncated). */
    limit?: number
    /** Additional class names on the trigger button. */
    triggerClassName?: string
    /** Additional class names on the popover content. */
    contentClassName?: string
}
```

**Example:**

```tsx
<NotificationCenter
  items={[
    { id: "1", title: "New comment", description: "Lina replied to your post", timestamp: "5m ago", read: false },
    { id: "2", title: "Build passed", timestamp: "1h ago", read: true },
  ]}
  onMarkRead={(id) => api.read(id)}
  onMarkAllRead={() => api.readAll()}
/>
```

---

## Number Input

**Description:** Numeric input with ± stepper buttons, min/max clamping, configurable step + precision.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/number-input.json
```

**Props:**

```ts
export interface NumberInputProps extends SaasflareComponentProps {
    /** Controlled value. */
    value?: number
    /** Uncontrolled initial value. */
    defaultValue?: number
    /** Called when the value changes (after clamp). */
    onChange?: (value: number) => void
    /** Minimum allowed value. */
    min?: number
    /** Maximum allowed value. */
    max?: number
    /** Step for stepper buttons + arrow keys. Default: `1`. */
    step?: number
    /** Decimal precision for display. Default: derived from `step`. */
    precision?: number
    /** Placeholder shown when empty. */
    placeholder?: string
    /** Disable the input. */
    disabled?: boolean
    /** Read-only input. */
    readOnly?: boolean
    /** Hide the stepper buttons. */
    hideSteppers?: boolean
    /** Additional class names on the outer wrapper. */
    className?: string
    /** Name attribute (for form submission). */
    name?: string
    /** Accessible label. */
    "aria-label"?: string
}
```

**Example:**

```tsx
const [n, setN] = useState(1);
<NumberInput value={n} onChange={setN} min={0} max={10} step={1} />
```

---

## Page Header

**Description:** Page header block with breadcrumbs, title, description, and an action slot for primary buttons.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/page-header.json
```

**Props:**

```ts
interface PageHeaderProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
  /** Page title */
  title: string
  /** Optional description below the title */
  description?: string
  /** Optional breadcrumb element rendered above the title */
  breadcrumbs?: React.ReactNode
  /** Action slot (buttons, etc.) aligned to the right */
  actions?: React.ReactNode
}
```

**Example:**

```tsx
import { PageHeader } from "@saasflare/ui";

<PageHeader
  title="Team Settings"
  description="Manage your team members and their permissions."
  actions={<Button>Invite Member</Button>}
/>
```

---

## Page Transition

**Description:** Wraps route content with enter/exit animations for smooth client-side page transitions.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/page-transition.json
```

**Props:**

```ts
export interface PageTransitionProps
  extends Omit<
      React.ComponentProps<"div">,
      MotionConflicts | "children" | keyof SaasflareComponentProps
    >,
    SaasflareComponentProps {
  /** Child content to animate. */
  children: ReactNode
  /** Animation preset. Default: `"fade"` */
  variant?: keyof typeof VARIANTS
  /** Transition duration in seconds. Default: `0.3` */
  duration?: number
  /**
   * Unique key for AnimatePresence to trigger re-animation on route changes.
   * Default: the current pathname (Next.js App Router).
   */
  transitionKey?: string
}
```

**Example:**

```tsx
import { PageTransition } from '@saasflare/ui';
// In your layout.tsx — the current pathname is used as the animation key.
export default function Layout({ children }: { children: React.ReactNode }) {
  return <PageTransition>{children}</PageTransition>;
}
```

---

## Pagination

**Description:** Page navigation with previous/next, page numbers, and ellipsis truncation for long ranges.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/pagination.json
```

**Props:**

```ts
interface PaginationProps
  extends Omit<React.ComponentProps<"nav">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Pagination root — semantic `<nav>` landmark wrapping the page controls.
 *
 * Carries the theme axes (`surface`/`radius`/`animated`) so descendant links
 * can inherit the active design-system context.
 */
function Pagination({
  className,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext } from '@saasflare/ui';
<Pagination>
  <PaginationContent>
    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
    <PaginationItem><PaginationLink href="#" isActive>1</PaginationLink></PaginationItem>
    <PaginationItem><PaginationLink href="#">2</PaginationLink></PaginationItem>
    <PaginationItem><PaginationNext href="#" /></PaginationItem>
  </PaginationContent>
</Pagination>
```

---

## Parallax Section

**Description:** Scroll-driven parallax where children move at a different rate than the page, adding depth.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/parallax-section.json
```

**Props:**

```ts
export interface ParallaxSectionProps extends SaasflareComponentProps {
  /** Content to apply parallax to. */
  children: ReactNode
  /** Parallax speed factor. 0 = fixed, 0.5 = half speed, 1 = no parallax. Default: `0.5` */
  speed?: number
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { ParallaxSection } from '@saasflare/ui';
<ParallaxSection speed={0.5}>
  <img src="/background.jpg" alt="Background" className="w-full" />
</ParallaxSection>
```

---

## Particles Background

**Description:** Floating particle field that drifts with subtle parallax. Ambient backdrop for heroes and sections.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/particles-background.json
```

**Props:**

```ts
export interface ParticlesBackgroundProps extends SaasflareComponentProps {
  /** Number of particles. Default: `20` */
  count?: number
  /** CSS color of particles. Default: `"var(--primary)"` */
  color?: string
  /** Maximum particle diameter in pixels. Default: `4` */
  maxSize?: number
  /** Minimum particle diameter in pixels. Default: `1` */
  minSize?: number
  /** Maximum particle opacity (0–1). Default: `0.3` */
  maxOpacity?: number
  /** Animation speed multiplier. Default: `1` */
  speed?: number
  /** Additional class names for the container. */
  className?: string
}
```

**Example:**

```tsx
import { ParticlesBackground } from '@saasflare/ui';
<div className="relative min-h-screen">
  <ParticlesBackground />
  <div className="relative z-10">Your content</div>
</div>
```

---

## Popover

**Description:** Floating panel anchored to a trigger — for pickers, menus, and contextual forms.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/popover.json
```

**Example:**

```tsx
import { Popover, PopoverTrigger, PopoverContent } from '@saasflare/ui';

<Popover>
  <PopoverTrigger>Open</PopoverTrigger>
  <PopoverContent>
    <p>Popover content here.</p>
  </PopoverContent>
</Popover>
```

---

## Pricing Card

**Description:** Pricing plan card with title, price, feature list, CTA, and an optional 'Popular' pill.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/pricing-card.json
```

**Props:**

```ts
interface PricingCardProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
  /** Plan name (e.g. "Starter", "Pro", "Enterprise") */
  name: string
  /** Formatted price (e.g. "$29", "Free", "$99") */
  price: string
  /** Billing period (e.g. "month", "year") */
  period?: string
  /** Short plan description */
  description?: string
  /** List of included features */
  features: string[]
  /** CTA button element */
  cta?: React.ReactNode
  /** Highlight as recommended plan */
  featured?: boolean
}
```

**Example:**

```tsx
import { PricingCard } from "@saasflare/ui";

<PricingCard
  name="Pro"
  price="$29"
  period="month"
  description="For growing teams"
  features={["Unlimited projects", "Priority support", "Analytics"]}
  cta={<Button>Get Started</Button>}
  featured
/>
```

---

## Progress

**Description:** Linear determinate progress bar for uploads, completion meters, and loading states.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/progress.json
```

**Props:**

```ts
interface ProgressProps
  extends Omit<React.ComponentProps<typeof ProgressPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Progress bar with smooth spring animation.
 *
 * @component
 * @layer core
 *
 * @param {number} value - Progress value (0-100)
 *
 * @example
 * <Progress value={42} className="w-full" />
 */
function Progress({
  className,
  value,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Progress } from "@saasflare/ui";
<Progress value={65} />
```

---

## Progress Circle

**Description:** Circular progress indicator. Radial counterpart to Progress, common for KPI rings.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/progress-circle.json
```

**Props:**

```ts
export interface ProgressCircleProps extends SaasflareComponentProps {
    /** Current value in the range `[0, max]`. */
    value: number
    /** Maximum value. Default: `100`. */
    max?: number
    /** Size preset. Default: `"md"`. */
    size?: ProgressCircleSize
    /** Ring stroke width in pixels. Default: derived from `size`. */
    strokeWidth?: number
    /** Center content (e.g. the numeric label). */
    children?: ReactNode
    /** Additional class names on the outer wrapper. */
    className?: string
    /** Accessible label. Default: `"<value>%"`. */
    "aria-label"?: string
}
```

**Example:**

```tsx
<ProgressCircle value={72} />
```

---

## Radio Group

**Description:** Mutually exclusive option set with keyboard arrow navigation and accessible grouping.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/radio-group.json
```

**Props:**

```ts
interface RadioGroupProps
  extends Omit<React.ComponentProps<typeof RadioGroupPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Accessible radio button group. Wrap one or more {@link RadioGroupItem}s and
 * control the active value via `value`/`defaultValue`. Honors the `surface`,
 * `radius`, and `animated` axes through {@link useSaasflareProps}.
 *
 * @example
 * <RadioGroup defaultValue="weekly">
 *   <RadioGroupItem value="weekly" />
 *   <RadioGroupItem value="monthly" />
 * </RadioGroup>
 */
function RadioGroup({
  className,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { RadioGroup, RadioGroupItem } from '@saasflare/ui';
<RadioGroup defaultValue="option-1">
  <RadioGroupItem value="option-1" />
  <RadioGroupItem value="option-2" />
</RadioGroup>
```

---

## Rating

**Description:** Star rating input with half-star precision, keyboard arrows, and read-only display mode.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/rating.json
```

**Props:**

```ts
export interface RatingProps extends SaasflareComponentProps {
    /** Controlled value (0..count). */
    value?: number
    /** Uncontrolled initial value. */
    defaultValue?: number
    /** Called when the user clicks a star. */
    onChange?: (value: number) => void
    /** Number of stars. Default: `5`. */
    count?: number
    /** Allow half-star granularity. Default: `false`. */
    allowHalf?: boolean
    /** Read-only display mode (no interaction, no hover preview). */
    readOnly?: boolean
    /** Disable the rating. */
    disabled?: boolean
    /** Star size. Default: `"md"`. */
    size?: RatingSize
    /** Star color (any CSS color). Default: `var(--warning)` — brand-independent gold. */
    color?: string
    /** Additional class names. */
    className?: string
    /** Accessible label. */
    "aria-label"?: string
}
```

**Example:**

```tsx
const [score, setScore] = useState(0);
<Rating value={score} onChange={setScore} allowHalf />
```

---

## Resizable

**Description:** Draggable split panes with persistent sizes for dashboards and editor layouts.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/resizable.json
```

**Example:**

```tsx
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@saasflare/ui';
<ResizablePanelGroup direction="horizontal">
  <ResizablePanel>Left</ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel>Right</ResizablePanel>
</ResizablePanelGroup>
```

---

## Retro Grid

**Description:** CSS-only perspective grid receding to the horizon — a synthwave landing-page backdrop.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/retro-grid.json
```

**Props:**

```ts
export interface RetroGridProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Grid line color. Default: `"var(--border)"` */
  gridColor?: string
  /** Grid cell size in pixels. Default: `60` */
  gridSize?: number
  /** Perspective tilt angle in degrees. Default: `65` */
  angle?: number
  /** Grid line opacity (0–1). Default: `0.4` */
  opacity?: number
}
```

**Example:**

```tsx
import { RetroGrid } from '@saasflare/ui';
<div className="relative min-h-[500px]">
  <RetroGrid />
  <div className="relative z-10">Hero content</div>
</div>
```

---

## Reveal On Scroll

**Description:** Animates elements into view as they enter the viewport (Intersection Observer + Motion).

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/reveal-on-scroll.json
```

**Props:**

```ts
export interface RevealOnScrollProps
  extends Omit<React.ComponentProps<"div">, MotionConflicts | keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Direction the element slides in from. Default: `"up"` */
  direction?: RevealDirection
  /** Animation delay in seconds. Default: `0` */
  delay?: number
  /** Intersection Observer root margin. Default: `"-80px"` */
  rootMargin?: string
  /** Whether the animation triggers only once. Default: `true` */
  once?: boolean
}
```

**Example:**

```tsx
import { RevealOnScroll } from '@saasflare/ui';
<RevealOnScroll>
  <Card>Appears when scrolled into view</Card>
</RevealOnScroll>
```

---

## Scroll Area

**Description:** Cross-browser custom scrollbars for overflow regions, keeping native scroll performance.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/scroll-area.json
```

**Props:**

```ts
interface ScrollAreaProps
  extends Omit<React.ComponentProps<typeof ScrollAreaPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Scrollable container that replaces native scrollbars with a styled,
 * cross-browser thumb, built on Radix UI ScrollArea. Constrain it with a
 * height or width class and place overflowing content inside.
 *
 * @component
 * @layer core
 */
function ScrollArea({
  className,
  children,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { ScrollArea } from '@saasflare/ui';
<ScrollArea className="h-72">
  <div>Scrollable content here</div>
</ScrollArea>
```

---

## Search Field

**Description:** Search input with built-in search icon, clear button, and optional loading spinner.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/search-field.json
```

**Props:**

```ts
interface SearchFieldProps extends Omit<React.ComponentProps<"input">, "type" | keyof SaasflareComponentProps>, SaasflareComponentProps {
  /** Show loading spinner instead of search icon */
  loading?: boolean
  /** Callback when clear button is clicked */
  onClear?: () => void
}
```

**Example:**

```tsx
import { SearchField } from "@saasflare/ui";

<SearchField
  placeholder="Search projects..."
  value={query}
  onChange={(e) => setQuery(e.target.value)}
  onClear={() => setQuery("")}
/>
```

---

## Section Card

**Description:** Composable section/landing card with header, content, and footer slots.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/section-card.json
```

**Props:**

```ts
interface SectionCardProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
  /** Section title */
  title: string
  /** Optional description below the title */
  description?: string
  /** Optional footer content (save button, etc.) */
  footer?: React.ReactNode
  /** Optional action in the header (edit button, etc.) */
  headerAction?: React.ReactNode
}
```

**Example:**

```tsx
import { SectionCard } from "@saasflare/ui";

<SectionCard title="General" description="Basic project settings">
  <Input label="Project name" />
</SectionCard>
```

---

## Select

**Description:** Dropdown select with option groups and a styled trigger. Radix-backed and fully accessible.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/select.json
```

**Example:**

```tsx
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@saasflare/ui';
<Select>
  <SelectTrigger>
    <SelectValue placeholder="Pick an option" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="one">Option One</SelectItem>
    <SelectItem value="two">Option Two</SelectItem>
  </SelectContent>
</Select>
```

---

## Separator

**Description:** Thin horizontal or vertical divider for grouping content and menu sections.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/separator.json
```

**Props:**

```ts
interface SeparatorProps
  extends Omit<
      React.ComponentProps<typeof SeparatorPrimitive.Root>,
      keyof SaasflareComponentProps
    >,
    SaasflareComponentProps {}

/**
 * Separator — visual divider line for separating content horizontally or vertically.
 * Built on Radix UI Separator.
 *
 * @example
 * ```tsx
 * import { Separator } from '@saasflare/ui';
 *
 * <Separator orientation="horizontal" />
 * ```
 */
function Separator({
  className,
  orientation = "horizontal",
  decorative = true,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Separator } from '@saasflare/ui';
<Separator orientation="horizontal" />
```

---

## Settings Section

**Description:** Settings row layout — label and description on the left, control on the right. For preference screens.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/settings-section.json
```

**Props:**

```ts
interface SettingsSectionProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
  /** Setting label */
  label: string
  /** Optional description of the setting */
  description?: string
}
```

**Example:**

```tsx
import { SettingsSection } from "@saasflare/ui";

<SettingsSection
  label="Email Notifications"
  description="Receive email updates about your account activity."
>
  <Switch checked={enabled} onCheckedChange={setEnabled} />
</SettingsSection>
```

---

## Sheet

**Description:** Edge-anchored slide-in panel (top/right/bottom/left) for filters, details, and side forms.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/sheet.json
```

**Example:**

```tsx
import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription } from '@saasflare/ui';
<Sheet>
  <SheetTrigger>Open</SheetTrigger>
  <SheetContent side="right">
    <SheetHeader>
      <SheetTitle>Sheet Title</SheetTitle>
      <SheetDescription>Sheet description text.</SheetDescription>
    </SheetHeader>
  </SheetContent>
</Sheet>
```

---

## Shimmer Button

**Description:** CTA button with a looping diagonal light sweep. Draws the eye to your primary action.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/shimmer-button.json
```

**Props:**

```ts
export interface ShimmerButtonProps
  extends Omit<React.ComponentProps<"button">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Button content. */
  children: ReactNode
  /** Color of the shimmer highlight. Default: `"var(--primary-foreground)"` */
  shimmerColor?: string
  /** Shimmer cycle duration in seconds. Default: `2.5` */
  speed?: number
  /** Background color. Default: `"var(--primary)"` */
  background?: string
}
```

**Example:**

```tsx
import { ShimmerButton } from '@saasflare/ui';
<ShimmerButton>Get Started Free</ShimmerButton>
```

---

## Skeleton

**Description:** Animated placeholder block for loading states — mirror your content's shape to avoid layout shift.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/skeleton.json
```

**Props:**

```ts
interface SkeletonProps extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
  /**
   * Component shape to imitate. When set, radius follows the design-system
   * scale (and at `data-radius="pill"`, all variants collapse to fully rounded
   * automatically — see theme.css).
   *
   * - `avatar` → fully rounded
   * - `text`   → `--radius-sm`
   * - `card`   → `--radius-lg`
   *
   * Omit for legacy behavior (`rounded-md` Tailwind class).
   */
  as?: SkeletonAs
}
```

**Example:**

```tsx
import { Skeleton } from "@saasflare/ui";
<Skeleton as="text" className="h-4 w-48" />
<Skeleton as="avatar" className="h-12 w-12" />
<Skeleton as="card" className="h-40 w-full" />
```

---

## Slider

**Description:** Draggable value selector with single or range thumbs, steps, and keyboard control.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/slider.json
```

**Props:**

```ts
interface SliderProps
  extends Omit<React.ComponentProps<typeof SliderPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Range slider for selecting one or more numeric values along a track. Renders
 * one thumb per value with spring-animated hover/press scaling; supports
 * horizontal and vertical layouts via the Radix `orientation` prop.
 *
 * @component
 * @layer core
 *
 * @example
 * <Slider defaultValue={[50]} max={100} step={1} />
 */
function Slider({
  className,
  defaultValue,
  value,
  min = 0,
  max = 100,
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Slider } from '@saasflare/ui';
<Slider defaultValue={[50]} max={100} step={1} />
```

---

## Social Button

**Description:** Compact branded sign-in button for five core providers (Google, Apple, GitHub, Microsoft, Twitter) with official logos and brand colors. For the full 16-provider OAuth set, see Social Auth Button.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/social-button.json
```

**Props:**

```ts
export interface SocialButtonProps
  extends Omit<ComponentProps<"button">, "children" | keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Social provider to render. */
  provider: SocialButtonProvider
  /** Override the default label text. */
  label?: string
  /** Show only the icon (no text). Default: `false` */
  iconOnly?: boolean
}
```

**Example:**

```tsx
import { SocialAuthButton } from '@saasflare/ui'; // preferred
<SocialAuthButton provider="google" onClick={() => signInWithGoogle()} />
```

---

## Toaster

**Description:** Toast notifications — themed, stacked, and promise-aware (Sonner) with Phosphor icons and dark-mode support.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/sonner.json
```

**Example:**

```tsx
import { Toaster } from '@saasflare/ui';
<Toaster position="top-right" />
```

---

## Spark Chart

**Description:** Inline mini line/area/bar chart. Pure SVG, no recharts. Tucks inside metric cards.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/spark-chart.json
```

**Props:**

```ts
export interface SparkChartProps extends SaasflareComponentProps {
    /** Series of numeric points (length ≥ 2). */
    data: number[]
    /** Visual treatment. Default: `"area"`. */
    variant?: SparkChartVariant
    /** Stroke / fill color (any CSS color). Default: `var(--primary)`. */
    color?: string
    /** SVG width in pixels. Default: `64`. */
    width?: number
    /** SVG height in pixels. Default: `24`. */
    height?: number
    /** Line stroke width in pixels. Default: `1.5`. */
    strokeWidth?: number
    /** Additional class names. */
    className?: string
    /** Accessible label. */
    "aria-label"?: string
}
```

**Example:**

```tsx
<SparkChart data={[3, 5, 4, 8, 6, 9, 11]} variant="area" />
```

---

## Spinner

**Description:** Indeterminate loading spinner (Phosphor CircleNotch) for buttons and async regions.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/spinner.json
```

**Props:**

```ts
interface SpinnerProps extends Omit<React.ComponentProps<"svg">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/**
 * Loading indicator — a spinning Phosphor CircleNotch with `role="status"` and
 * an accessible "Loading" label. The spin animation respects the resolved
 * `animated` axis. Size via `className` (defaults to `size-4`).
 *
 * @component
 * @layer core
 *
 * @example
 * <Spinner className="size-6" />
 */
function Spinner({ className, surface, radius, animated, iconWeight, ...props }: SpinnerProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })

  return (
    <CircleNotchIcon
      {...props}
      role="status"
      aria-label="Loading"
      data-slot="spinner"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
      className={cn("size-4", sf.animated && "animate-spin", className)}
    />
  )
}
```

**Example:**

```tsx
import { Spinner } from '@saasflare/ui';
<Spinner className="size-6" />
```

---

## Spotlight Card

**Description:** Card with a cursor-following spotlight gradient effect on hover.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/spotlight-card.json
```

**Props:**

```ts
export interface SpotlightCardProps
  extends Omit<React.ComponentProps<"div">, MotionConflicts | keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Card content. */
  children: ReactNode
  /** Spotlight gradient color. Default: `"var(--primary)"` */
  spotlightColor?: string
  /** Spotlight diameter in pixels. Default: `250` */
  spotlightSize?: number
  /** Spotlight opacity (0–1). Default: `0.08` */
  spotlightOpacity?: number
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { SpotlightCard } from '@saasflare/ui';
<SpotlightCard>
  <h3>Feature Title</h3>
  <p>Feature description text</p>
</SpotlightCard>
```

---

## Stat Card

**Description:** KPI / metric card with icon, large value, label, and optional delta indicator.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/stat-card.json
```

**Props:**

```ts
export interface StatCardProps extends SaasflareComponentProps {
  /** The stat value (e.g. "10K+", "99.9%", "$2.4M"). */
  value: string
  /** Label describing the stat. */
  label: string
  /** Optional icon displayed above the value. */
  icon?: ReactNode
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { StatCard } from '@saasflare/ui';
<StatCard value="10K+" label="Active Users" />
```

---

## Steps

**Description:** Horizontal or vertical step indicator showing progress through a multi-stage flow or wizard.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/steps.json
```

**Props:**

```ts
export interface StepsProps extends SaasflareComponentProps {
  /** Step children. */
  children: ReactNode
  /** Index of the current active step (0-based). Default: `0` */
  current?: number
  /** Layout direction. Default: `"horizontal"` */
  direction?: "horizontal" | "vertical"
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { Steps, Step } from '@saasflare/ui';
<Steps current={1}>
  <Step title="Sign Up" />
  <Step title="Configure" />
  <Step title="Deploy" />
</Steps>
```

---

## Stepper

**Description:** Controlled multi-step wizard — a useStepper hook plus Stepper / StepperNav / StepperPanel with linear or non-linear flow, optional steps, and async validation gating.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/stepper.json
```

**Props:**

```ts
export interface StepperProps extends SaasflareComponentProps {
    /** Step metadata for the indicator. Length defines the step count. */
    items: ReadonlyArray<StepperItem>
    /** Indicator layout (forwarded to `Steps`). Default: `"horizontal"` */
    direction?: "horizontal" | "vertical"
    /** Linear mode forwarded to the internal hook. Default: `true` */
    linear?: boolean
    /** Bring-your-own hook instance (controlled). When omitted, Stepper owns one. */
    stepper?: UseStepperReturn
    /** Initial step when Stepper owns the hook (uncontrolled). Default: `0` */
    defaultStep?: number
    /** Global validation gate (uncontrolled mode only). */
    validate?: (
        step: number,
    ) => boolean | string | void | Promise<boolean | string | void>
    /** Fired on finish (uncontrolled mode only). */
    onComplete?: () => void
    /** `"unmount"` = only active panel in DOM; `"keepMounted"` = all panels mounted, inactive hidden. Default: `"unmount"` */
    mountMode?: "unmount" | "keepMounted"
    /** Hide the built-in `<StepperNav>`. Default: `false` */
    hideNav?: boolean
    /** Panel children — one `<StepperPanel>` per step, in order. */
    children: ReactNode
    /** Class for the root. */
    className?: string
}
```

**Example:**

```tsx
import { Stepper, StepperPanel } from "@saasflare/ui";

<Stepper
  items={[{ title: "Account" }, { title: "Profile" }, { title: "Done" }]}
>
  <StepperPanel value={0}>Account fields…</StepperPanel>
  <StepperPanel value={1}>Profile fields…</StepperPanel>
  <StepperPanel value={2}>All set!</StepperPanel>
</Stepper>
```

---

## Sticky Scroll Reveal

**Description:** Split layout where the left column pins while the right scrolls through synced content steps.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/sticky-scroll-reveal.json
```

**Props:**

```ts
export interface StickyScrollRevealProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Array of scroll items. */
  items: StickyScrollItem[]
}
```

**Example:**

```tsx
import { StickyScrollReveal } from '@saasflare/ui';
<StickyScrollReveal
  items={[
    { title: "Step 1", description: "Connect your data", content: <img src="/step1.png" /> },
    { title: "Step 2", description: "Configure your pipeline", content: <img src="/step2.png" /> },
  ]}
/>
```

---

## Switch

**Description:** On/off toggle for boolean settings, with size variants and accessible labeling.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/switch.json
```

**Props:**

```ts
interface SwitchProps
  extends Omit<React.ComponentProps<typeof SwitchPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Visual size of the toggle. `md` is the standard control; `sm` is a compact variant for dense rows. (`"default"` is a deprecated alias for `"md"`.) */
  size?: "sm" | "md" | "default"
}
```

**Example:**

```tsx
import { Switch } from '@saasflare/ui';
<Switch checked={enabled} onCheckedChange={setEnabled} />
<Switch size="sm" />
```

---

## Table

**Description:** Composable data table with header, body, row, cell, and caption sub-components.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/table.json
```

**Props:**

```ts
interface TableProps extends Omit<React.ComponentProps<"table">, keyof SaasflareComponentProps>, SaasflareComponentProps {}

/**
 * Data table root — a styled `<table>` wrapped in a horizontally scrollable
 * container so wide tables stay usable on narrow viewports. Compose with
 * {@link TableHeader}, {@link TableBody}, {@link TableRow}, and friends.
 *
 * @component
 * @layer core
 */
function Table({ className, surface, radius, animated, iconWeight, ...props }: TableProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })

  return (
    <div
      data-slot="table-container"
      className="relative w-full overflow-x-auto"
    >
      <table
        {...props}
        data-slot="table"
        data-surface={sf.surface}
        data-radius={sf.radius}
        data-animated={String(sf.animated)}
        className={cn("w-full caption-bottom text-sm", className)}
      />
    </div>
  )
}
```

**Example:**

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@saasflare/ui';
<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Status</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Acme Corp</TableCell>
      <TableCell>Active</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

---

## Tabs

**Description:** Switch between panels of related content with keyboard navigation and an animated active indicator.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/tabs.json
```

**Props:**

```ts
interface TabsProps
  extends Omit<React.ComponentProps<typeof TabsPrimitive.Root>, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Tabbed navigation root built on Radix Tabs, with an animated indicator that
 * tracks the active trigger. Owns the active value and orientation; compose
 * with {@link TabsList}, {@link TabsTrigger}, and {@link TabsContent}.
 *
 * @component
 * @layer core
 */
function Tabs({
  className,
  orientation = "horizontal",
  surface,
  radius,
  animated,
  iconWeight,
  ...props
}
```

**Example:**

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@saasflare/ui";
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">...</TabsContent>
  <TabsContent value="settings">...</TabsContent>
</Tabs>
```

---

## Tag Input

**Description:** Input that converts entries into removable pill tags on Enter / comma. Controlled or uncontrolled.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/tag-input.json
```

**Props:**

```ts
export interface TagInputProps extends SaasflareComponentProps {
    /** Controlled list of tags. */
    value?: string[]
    /** Uncontrolled initial tags. */
    defaultValue?: string[]
    /** Called whenever the tag list changes. */
    onChange?: (tags: string[]) => void
    /** Placeholder shown in the input. */
    placeholder?: string
    /** Maximum number of tags accepted. */
    maxTags?: number
    /** Characters that commit the current input as a tag. Default: `[",", "Enter"]`. */
    separators?: string[]
    /** Reject duplicate tags. Default: `true`. */
    unique?: boolean
    /** Disable the input. */
    disabled?: boolean
    /** Custom renderer for each pill. Falls back to the default pill UI. */
    renderTag?: (tag: string, onRemove: () => void) => ReactNode
    /** Additional class names on the outer wrapper. */
    className?: string
    /** Accessible label. */
    "aria-label"?: string
}
```

**Example:**

```tsx
const [tags, setTags] = useState<string[]>([]);
<TagInput value={tags} onChange={setTags} placeholder="Add a tag…" />
```

---

## Team Card

**Description:** Team member card with photo, name, role, bio, and social links.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/team-card.json
```

**Props:**

```ts
export interface TeamCardProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Person's name. */
  name: string
  /** Role or job title. */
  role: string
  /** Photo URL. */
  photo?: string
  /** Short bio text. */
  bio?: string
  /** Social media links. */
  socials?: SocialLink[]
}
```

**Example:**

```tsx
import { TeamCard } from '@saasflare/ui';
<TeamCard
  name="Jane Doe"
  role="CEO & Co-Founder"
  photo="/team/jane.jpg"
  socials={[
    { label: "Twitter", url: "https://twitter.com/jane", icon: <TwitterIcon /> },
    { label: "LinkedIn", url: "https://linkedin.com/in/jane", icon: <LinkedInIcon /> },
  ]}
/>
```

---

## Testimonial Card

**Description:** Customer testimonial card with quote, author name, role, and optional avatar.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/testimonial-card.json
```

**Props:**

```ts
export interface TestimonialCardProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** The testimonial quote text. */
  quote: string
  /** Name of the person. */
  name: string
  /** Role/title of the person. */
  role?: string
  /** Avatar image URL. */
  avatar?: string
  /** Star rating (1–5). Omit to hide stars. */
  rating?: 1 | 2 | 3 | 4 | 5
}
```

**Example:**

```tsx
import { TestimonialCard } from '@saasflare/ui';
<TestimonialCard
  quote="Amazing product!"
  name="Jane Doe"
  role="CEO at Acme"
  avatar="/jane.jpg"
  rating={5}
/>
```

---

## Text Generate Effect

**Description:** Reveals text word-by-word for a typing/AI-generation feel. For hero copy and intros.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/text-generate-effect.json
```

**Props:**

```ts
export interface TextGenerateEffectProps extends SaasflareComponentProps {
  /** Text string to animate word by word. */
  text: string
  /** Delay between each word in seconds. Default: `0.05` */
  stagger?: number
  /** Duration per word fade-in in seconds. Default: `0.4` */
  duration?: number
  /** Whether animation triggers only once. Default: `true` */
  once?: boolean
  /** HTML element to render. Default: `"p"` */
  as?: "p" | "h1" | "h2" | "h3" | "h4" | "span"
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { TextGenerateEffect } from '@saasflare/ui';
<TextGenerateEffect text="Build your SaaS in record time" />
```

---

## Textarea

**Description:** Multi-line text field with intent states and auto-sizing support for comments and messages.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/textarea.json
```

**Props:**

```ts
interface TextareaProps
  extends Omit<TextareaBaseProps, keyof SaasflareComponentProps>,
    SaasflareComponentProps {}

/**
 * Multi-line text input with a spring-animated focus ring and content-based
 * auto-sizing (`field-sizing-content`). `surface`, `radius`, and `animated`
 * resolve against the <SaasflareProvider> context when omitted.
 *
 * @component
 * @layer core
 */
function Textarea({ className, surface, radius, animated, iconWeight, ...props }: TextareaProps) {
  const sf = useSaasflareProps({ surface, radius, animated, iconWeight })
  const motion = useSaasflareMotion(sf.animated, { type: "spring", stiffness: 300, damping: 20 })

  return (
    <m.textarea
      {...props}
      data-slot="textarea"
      data-surface={sf.surface}
      data-radius={sf.radius}
      data-animated={String(sf.animated)}
      whileFocus={motion.disabled ? undefined : { boxShadow: "0 0 0 3px color-mix(in oklab, var(--ring) 30%, transparent)" }}
      transition={motion.transition}
      className={cn(
        "w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-2 text-base shadow-xs transition-[color,border-color] outline-none selection:bg-primary selection:text-primary-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:bg-input/30",
        "field-sizing-content min-h-16",
        "focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50",
        "aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40",
        className
      )}
    />
  )
}
```

**Example:**

```tsx
import { Textarea } from '@saasflare/ui';
<Textarea placeholder="Write your message..." />
```

---

## Timeline

**Description:** Vertical scroll-driven timeline whose beam fills as the reader progresses. For changelogs and stories.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/timeline.json
```

**Props:**

```ts
export interface TimelineProps extends SaasflareComponentProps {
  /** TimelineItem children. */
  children: ReactNode
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { Timeline, TimelineItem } from '@saasflare/ui';
<Timeline>
  <TimelineItem title="v2.0 Released" date="March 2026">
    Major redesign with new dashboard.
  </TimelineItem>
  <TimelineItem title="v1.5 Released" date="January 2026">
    Added billing module.
  </TimelineItem>
</Timeline>
```

---

## Toggle

**Description:** Two-state pressable button for toolbars (bold/italic), with outline and size variants.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/toggle.json
```

**Props:**

```ts
interface ToggleProps
  extends Omit<React.ComponentProps<typeof TogglePrimitive.Root>, keyof SaasflareComponentProps>,
    Omit<VariantProps<typeof toggleVariants>, "size">,
    SaasflareComponentProps {
  /** Visual size. (`"default"` is a deprecated alias for `"md"`.) */
  size?: VariantProps<typeof toggleVariants>["size"] | "default"
}
```

**Example:**

```tsx
import { Toggle } from '@saasflare/ui';
<Toggle variant="outline" aria-label="Toggle bold">
  <BoldIcon className="size-4" />
</Toggle>
```

---

## Toggle Group

**Description:** Set of toggles for single- or multi-select segmented controls (alignment, view modes).

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/toggle-group.json
```

**Example:**

```tsx
import { ToggleGroup, ToggleGroupItem } from '@saasflare/ui';
<ToggleGroup type="single" defaultValue="center">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>
```

---

## Tooltip

**Description:** Hover/focus hint label anchored to any element, with configurable delay and side positioning.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/tooltip.json
```

**Example:**

```tsx
import { TooltipProvider, Tooltip, TooltipTrigger, TooltipContent } from '@saasflare/ui';
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger>Hover me</TooltipTrigger>
    <TooltipContent>Helpful hint</TooltipContent>
  </Tooltip>
</TooltipProvider>
```

---

## Tracing Beam

**Description:** Animated vertical line that traces the reader's scroll progress alongside long-form content.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/tracing-beam.json
```

**Props:**

```ts
export interface TracingBeamProps
  extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
    SaasflareComponentProps {
  /** Content alongside the beam. */
  children: ReactNode
  /** Beam color. Default: `"var(--primary)"` */
  color?: string
  /** Track (background line) color. Default: `"var(--border)"` */
  trackColor?: string
  /** Additional class names. */
  className?: string
}
```

**Example:**

```tsx
import { TracingBeam } from '@saasflare/ui';
<TracingBeam>
  <article>
    <h1>Getting Started</h1>
    <p>Long form content here...</p>
  </article>
</TracingBeam>
```

---

## Tracker

**Description:** Uptime/status segment grid. Each block is one period (day/hour) colored by status.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/tracker.json
```

**Props:**

```ts
export interface TrackerProps
    extends Omit<React.ComponentProps<"div">, keyof SaasflareComponentProps>,
        SaasflareComponentProps {
    /** Blocks to render, left-to-right. */
    data: TrackerBlock[]
    /** Height of each block in px. Default: `32`. */
    blockHeight?: number
    /** Gap between blocks in px. Default: `2`. */
    gap?: number
    /** Additional class names. */
    className?: string
}
```

**Example:**

```tsx
<Tracker
  data={[
    { color: "emerald", tooltip: "Apr 1 — Operational" },
    { color: "emerald", tooltip: "Apr 2 — Operational" },
    { color: "amber",   tooltip: "Apr 3 — Degraded performance" },
    { color: "red",     tooltip: "Apr 4 — Major outage" },
  ]}
/>
```

---

## Tree View

**Description:** Recursive expand/collapse tree with keyboard navigation, controlled/uncontrolled expansion + selection.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/tree-view.json
```

**Props:**

```ts
export interface TreeViewProps extends SaasflareComponentProps {
    /** Tree data, top-level nodes. */
    data: TreeNode[]
    /** Controlled expanded ids. */
    expanded?: string[]
    /** Uncontrolled initial expansion. */
    defaultExpanded?: string[]
    /** Called when a node is expanded/collapsed. */
    onExpand?: (ids: string[]) => void
    /** Controlled selected id. */
    selected?: string | null
    /** Uncontrolled initial selection. */
    defaultSelected?: string | null
    /** Called when selection changes. */
    onSelect?: (id: string | null) => void
    /** Additional class names on the root. */
    className?: string
}
```

**Example:**

```tsx
<TreeView
  data={[
    {
      id: "src", label: "src",
      children: [
        { id: "src/app", label: "app" },
        { id: "src/lib", label: "lib", children: [{ id: "src/lib/cn", label: "cn.ts" }] },
      ],
    },
  ]}
/>
```

---

## Typewriter Text

**Description:** Types out text character-by-character with a blinking cursor. Classic hero headline effect.

**Install:**

```bash
npx shadcn add https://ui.saasflare.io/r/typewriter-text.json
```

**Props:**

```ts
interface TypewriterTextProps extends SaasflareComponentProps {
  text: string;
  /** Delay between each word in ms (default: 40) */
  wordDelay?: number;
  /** Skip animation and show full text immediately */
  skipAnimation?: boolean;
  /** Callback when animation completes */
  onComplete?: () => void;
  /** Additional class names */
  className?: string;
}
```

**Example:**

```tsx
import { TypewriterText } from '@saasflare/ui';
<TypewriterText text="Hello, welcome to Saasflare." wordDelay={60} />
```

---