# Junco: full reference

Junco is a free, open source (MIT) design system for React and Tailwind CSS v4: tokens, components, blocks, pages, motion and 3D. It can be used four ways, all reading the same tokens:

1. Semantic classes (like daisyUI): class="btn btn-primary". Pure CSS. Setup: @import "tailwindcss"; @import "@junco/tailwind";
2. Utilities (like Tailwind): bg-surface text-muted-foreground rounded-card. Same setup.
3. Copy-in components (like shadcn/ui): npx @junco/cli add button (or npx shadcn@latest add https://junco.madebytobi.com/r/button.json).
4. Installed components (like HeroUI): npm i junco, then import { Button } from "junco". Add @source "../node_modules/junco/dist"; to your CSS.

Tokens follow shadcn/ui names (--background, --foreground, --primary, --muted-foreground, --border, --ring, ...) plus Junco additions (--surface, --success, --warning, --success-text, --warning-text, --destructive-text, motion tokens). Dark mode: .dark or [data-theme="dark"] on <html>. Motion: data-motion="full|subtle|off", and prefers-reduced-motion always turns motion off.

## Accordion

Stacked sections that expand and collapse. Good for FAQs and settings groups. `type="single"` opens one at a time (add `collapsible` to allow closing it); `type="multiple"` doesn't.

Install:

```bash
npx @junco/cli add accordion
npx shadcn@latest add https://junco.madebytobi.com/r/accordion.json
```

Exports: accordionVariants, AccordionProps, Accordion, AccordionItem, AccordionTriggerProps, AccordionTrigger, AccordionContent

Variants:

- variant: line | card (default line)

Props of AccordionTrigger (also accepts React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>):

- headingLevel?: 2 | 3 | 4 | 5 | 6. The heading level wrapping the trigger, for a correct document outline. Default 3.
- classNames?: { heading?: string; icon?: string }

Usage:

```tsx
<Accordion type="single" collapsible>
  <AccordionItem value="a">
    <AccordionTrigger>Is it free?</AccordionTrigger>
    <AccordionContent>Yes, MIT licensed.</AccordionContent>
  </AccordionItem>
</Accordion>
```

## Avatar

A person or workspace picture that falls back to initials while loading or when the image fails.

Install:

```bash
npx @junco/cli add avatar
npx shadcn@latest add https://junco.madebytobi.com/r/avatar.json
```

Exports: avatarVariants, initials, AvatarProps, Avatar

Variants:

- size: xs | sm | md | lg (default md)
- shape: circle | square (default circle)

Props of Avatar (also accepts React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>, VariantProps<typeof avatarVariants>):

- src?: string
- name?: string. The person's name. Used as the image alt text and for fallback initials.
- fallback?: React.ReactNode. Shown while the image loads or when it fails. Defaults to the name's initials.
- classNames?: { root?: string; image?: string; fallback?: string }

## Badge

A short label for status or counts.

Install:

```bash
npx @junco/cli add badge
npx shadcn@latest add https://junco.madebytobi.com/r/badge.json
```

Exports: badgeVariants, BadgeProps, Badge

Variants:

- variant: solid | outline (default solid)
- color: neutral | primary | success | warning | danger (default neutral)
- hasDot: true (default false)

Props of Badge (also accepts Omit<React.HTMLAttributes<HTMLSpanElement>, "color">, VariantProps<typeof badgeVariants>):


## Breadcrumb

Shows where a page sits in the hierarchy, with links back up. Collapses long trails with maxItems.

Install:

```bash
npx @junco/cli add breadcrumb
npx shadcn@latest add https://junco.madebytobi.com/r/breadcrumb.json
```

Exports: BreadcrumbItemData, BreadcrumbProps, Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLinkProps, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis

Props of Breadcrumb (also accepts React.HTMLAttributes<HTMLElement>):

- items?: BreadcrumbItemData[]. Shorthand: render these items. Or compose BreadcrumbList / BreadcrumbItem yourself.
- maxItems?: number. With more items than this, the middle collapses to "…". Default: never collapse.
- separator?: React.ReactNode. Custom separator. Default a chevron.
- renderLink?: (item: BreadcrumbItemData, props: { className: string; children: React.ReactNode }) => React.ReactNode. Render links through your router, e.g. `(item, props) => <Link to={item.href} {...props} />`.
- classNames?: Partial<Record<"root" | "list" | "item" | "link" | "page" | "separator"

Props of BreadcrumbLink (also accepts React.AnchorHTMLAttributes<HTMLAnchorElement>):

- asChild?: boolean. Render your router's Link as the child.

Usage:

```tsx
<Breadcrumb items={[{ label: "Projects", href: "/projects" }, { label: "Junco" }]} />
```

## Button

Triggers an action. Variants solid, outline, soft, ghost and danger; isLoading shows a spinner and sets aria-busy.

Install:

```bash
npx @junco/cli add button
npx shadcn@latest add https://junco.madebytobi.com/r/button.json
```

Exports: buttonVariants, ButtonProps, Button

Variants:

- variant: solid | outline | soft | ghost | danger (default solid)
- size: sm | md | lg | icon (default md)

Props of Button (also accepts React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants>):

- asChild?: boolean. Render as the child element (for example a link) instead of a button.
- isLoading?: boolean. Shows a spinner, disables the button and sets aria-busy.

## Card

A bordered container for grouping related content, with header, title, description, action, content and footer parts.

Install:

```bash
npx @junco/cli add card
npx shadcn@latest add https://junco.madebytobi.com/r/card.json
```

Exports: cardVariants, CardProps, Card, CardHeader, CardTitleProps, CardTitle, CardDescription, CardAction, CardContent, CardFooter

Variants:

- variant: outline | muted | elevated | ghost (default outline)
- isInteractive: true (default false)

Props of Card (also accepts React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof cardVariants>):


Props of CardTitle (also accepts React.HTMLAttributes<HTMLHeadingElement>):

- as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6". Heading level. Default h3.

Usage:

```tsx
<Card>
  <CardHeader><CardTitle>Usage</CardTitle><CardDescription>Last 30 days</CardDescription></CardHeader>
  <CardContent>...</CardContent>
  <CardFooter>...</CardFooter>
</Card>
```

## Checkbox

A checkbox. `checked` can be true, false or "indeterminate". Pair it with a <Label htmlFor>.

Install:

```bash
npx @junco/cli add checkbox
npx shadcn@latest add https://junco.madebytobi.com/r/checkbox.json
```

Exports: checkboxVariants, CheckboxProps, Checkbox

Variants:

- size: sm | md | lg (default md)

Props of Checkbox (also accepts React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, VariantProps<typeof checkboxVariants>):

- isInvalid?: boolean

## Command

A searchable list of actions, built on cmdk. Use it inline, or as a ⌘K palette with CommandDialog.

Install:

```bash
npx @junco/cli add command
npx shadcn@latest add https://junco.madebytobi.com/r/command.json
```

Exports: Command, CommandInput, CommandList, CommandEmpty, CommandLoading, CommandGroup, CommandSeparator, CommandItem, CommandShortcut, CommandDialogProps, CommandDialog

Props of CommandDialog (also accepts React.ComponentPropsWithoutRef<typeof CommandPrimitive>):

- open?: boolean
- defaultOpen?: boolean
- onOpenChange?: (open: boolean) => void
- shortcut?: string | null. Letter that opens the palette with ⌘ (Mac) or Ctrl. Default "k". Pass null to turn the shortcut off.
- title?: string. Read by screen readers. Default "Command palette".
- description?: string
- classNames?: { content?: string; command?: string }

Usage:

```tsx
<CommandDialog>
  <CommandInput placeholder="Search…" />
  <CommandList>
    <CommandEmpty>No results.</CommandEmpty>
    <CommandGroup heading="Pages">
      <CommandItem onSelect={() => go("/settings")}>Settings<CommandShortcut>⌘,</CommandShortcut></CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>
```

## Dialog

Every dialog needs a DialogTitle. Hide it visually with `<DialogTitle isHidden>` when the design has no heading.

Install:

```bash
npx @junco/cli add dialog
npx shadcn@latest add https://junco.madebytobi.com/r/dialog.json
```

Exports: Dialog, DialogTrigger, DialogClose, DialogPortal, DialogOverlay, dialogVariants, DialogContentProps, useReturnFocus, DialogContent, DialogHeader, DialogFooter, DialogTitleProps, DialogTitle, DialogDescription

Variants:

- size: sm | md | lg | xl | full (default md)

Props of DialogContent (also accepts React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, VariantProps<typeof dialogVariants>):

- showClose?: boolean. Show the × button in the corner. Default true.
- closeLabel?: string. Accessible name for the × button. Default "Close".
- classNames?: { overlay?: string; content?: string; close?: string }

Props of DialogTitle (also accepts React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>):

- isHidden?: boolean. Keep the title for screen readers but hide it on screen.

Usage:

```tsx
<Dialog>
  <DialogTrigger asChild><Button>Edit profile</Button></DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
      <DialogDescription>Changes show up for your whole team.</DialogDescription>
    </DialogHeader>
    ...
    <DialogFooter><DialogClose asChild><Button variant="outline">Cancel</Button></DialogClose></DialogFooter>
  </DialogContent>
</Dialog>
```

## Dropdown Menu

Arrow keys move, Enter/Space select, typing jumps to an item, Esc closes and returns focus.

Install:

```bash
npx @junco/cli add dropdown-menu
npx shadcn@latest add https://junco.madebytobi.com/r/dropdown-menu.json
```

Exports: DropdownMenu, DropdownMenuTrigger, DropdownMenuGroup, DropdownMenuSub, DropdownMenuRadioGroup, DropdownMenuContent, menuItemVariants, DropdownMenuShortcut, DropdownMenuItemProps, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuSubTrigger, DropdownMenuSubContent

Variants:

- variant: default | danger (default default)
- inset: true

Props of DropdownMenuItem (also accepts React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item>, VariantProps<typeof menuItemVariants>):

- shortcut?: string. Shorthand for a trailing <DropdownMenuShortcut>.

Usage:

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild><Button variant="outline">Options</Button></DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuLabel>Account</DropdownMenuLabel>
    <DropdownMenuItem shortcut="⌘P">Profile</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="danger">Log out</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Empty State

What to show when there is nothing to show: say why, and offer the next step.

Install:

```bash
npx @junco/cli add empty-state
npx shadcn@latest add https://junco.madebytobi.com/r/empty-state.json
```

Exports: emptyStateVariants, EmptyStateProps, EmptyState

Variants:

- size: sm | md | lg (default md)
- isBordered: true (default false)

Props of EmptyState (also accepts Omit<React.HTMLAttributes<HTMLDivElement>, "title">, VariantProps<typeof emptyStateVariants>):

- icon?: React.ReactNode
- title: React.ReactNode
- description?: React.ReactNode
- actions?: React.ReactNode. Buttons for the next step. Lead with one primary action.
- titleAs?: "h2" | "h3" | "h4" | "p". Heading level for the title. Default h3.
- classNames?: Partial<Record<"root" | "icon" | "title" | "description" | "actions"

## Field

Label + control + help text + error, wired together.

Install:

```bash
npx @junco/cli add field
npx shadcn@latest add https://junco.madebytobi.com/r/field.json
```

Exports: useFieldControl, FieldProps, Field

Props of Field (also accepts Omit<React.HTMLAttributes<HTMLDivElement>, "children">):

- label?: React.ReactNode
- description?: React.ReactNode. Help text under the control.
- error?: React.ReactNode. Error message. Setting it marks the control invalid.
- isRequired?: boolean
- isDisabled?: boolean
- id?: string. Id for the control. Generated when omitted.
- classNames?: { root?: string; label?: string; description?: string; error?: string }
- children: React.ReactNode

Usage:

```tsx
<Field label="Email" description="Work email" error={errors.email}><Input /></Field>
```

## Icon

Renders any SVG icon at a type-scale size with the `--icon-stroke` weight. Decorative by default (hidden from screen readers); pass `label` when the icon carries meaning on its own.

Install:

```bash
npx @junco/cli add icon
npx shadcn@latest add https://junco.madebytobi.com/r/icon.json
```

Exports: iconVariants, IconProps, Icon

Variants:

- size: xs | sm | md | lg | xl (default md)

Props of Icon (also accepts Omit<React.SVGProps<SVGSVGElement>, "ref">, VariantProps<typeof iconVariants>):

- as: React.ElementType. The icon component to render, e.g. `Search` from lucide-react. Any SVG component works.
- label?: string. Makes the icon meaningful: read as an image with this name. Leave it out for decorative icons.

Usage:

```tsx
import { Search } from "lucide-react";
<Icon as={Search} />                      // decorative, next to text
<Icon as={Search} label="Search" />       // meaningful on its own
```

## Input

A single-line text field. Sizes sm, md and lg; isInvalid sets aria-invalid; picks up its label and errors from a Field.

Install:

```bash
npx @junco/cli add input
npx shadcn@latest add https://junco.madebytobi.com/r/input.json
```

Exports: inputVariants, InputProps, Input

Variants:

- size: sm | md | lg (default md)

Props of Input (also accepts Omit<React.InputHTMLAttributes<HTMLInputElement>, "size">, VariantProps<typeof inputVariants>):

- isInvalid?: boolean. Marks the field invalid (sets aria-invalid). Pair it with an error message linked by aria-describedby.

## Kbd

A keyboard key, e.g. `<Kbd>⌘</Kbd><Kbd>K</Kbd>`. Give symbols a `title` so they read clearly.

Install:

```bash
npx @junco/cli add kbd
npx shadcn@latest add https://junco.madebytobi.com/r/kbd.json
```

Exports: KbdProps, Kbd

Props of Kbd (also accepts React.HTMLAttributes<HTMLElement>):


## Label

A form label with an optional required marker.

Install:

```bash
npx @junco/cli add label
npx shadcn@latest add https://junco.madebytobi.com/r/label.json
```

Exports: LabelProps, Label

Props of Label (also accepts React.LabelHTMLAttributes<HTMLLabelElement>):

- isRequired?: boolean. Shows a required marker. Also set `required` on the control so assistive tech knows.

## Pagination

Numbered page links with previous/next. The current page has aria-current="page".

Install:

```bash
npx @junco/cli add pagination
npx shadcn@latest add https://junco.madebytobi.com/r/pagination.json
```

Exports: PaginationItem, UsePaginationOptions, getPaginationItems, usePagination, PaginationProps, Pagination

Props of Pagination (also accepts Omit<React.HTMLAttributes<HTMLElement>, "onChange">):

- page: number
- pageCount: number
- onPageChange: (page: number) => void
- siblings?: number
- boundaries?: number
- getHref?: (page: number) => string. Builds a URL per page so each page is a real link (better for SEO and middle-click).
- size?: "sm" | "md"
- isCompact?: boolean. Hide the numbered pages (prev/next + "Page x of y"), e.g. on narrow screens.
- label?: string. Accessible name for the nav. Default "Pagination".
- classNames?: Partial<Record<"root" | "list" | "item" | "ellipsis" | "summary"

Usage:

```tsx
usePagination({ page: 6, pageCount: 20 }) // [1, "ellipsis-start", 5, 6, 7, "ellipsis-end", 20]
```

## Popover

Focus moves into the popover on open and back to the trigger on close. Esc and outside clicks close it.

Install:

```bash
npx @junco/cli add popover
npx shadcn@latest add https://junco.madebytobi.com/r/popover.json
```

Exports: Popover, PopoverTrigger, PopoverAnchor, PopoverClose, PopoverContent

Usage:

```tsx
<Popover>
  <PopoverTrigger asChild><Button variant="outline">Share</Button></PopoverTrigger>
  <PopoverContent>...</PopoverContent>
</Popover>
```

## Radio Group

Arrow keys move between options; Tab leaves the group. Give the group an aria-label or aria-labelledby.

Install:

```bash
npx @junco/cli add radio-group
npx shadcn@latest add https://junco.madebytobi.com/r/radio-group.json
```

Exports: radioVariants, RadioGroupProps, RadioGroup, RadioProps, Radio

Variants:

- size: sm | md | lg (default md)

Props of RadioGroup (also accepts React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>):


Props of Radio (also accepts React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>, VariantProps<typeof radioVariants>):


## Select

A dropdown for picking one option from a list, with keyboard type-ahead and a check on the chosen item.

Install:

```bash
npx @junco/cli add select
npx shadcn@latest add https://junco.madebytobi.com/r/select.json
```

Exports: Select, SelectValue, SelectGroup, selectTriggerVariants, SelectTriggerProps, SelectTrigger, SelectContent, SelectItem, SelectLabel, SelectSeparator

Variants:

- size: sm | md | lg (default md)

Props of SelectTrigger (also accepts React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>, VariantProps<typeof selectTriggerVariants>):

- isInvalid?: boolean

Usage:

```tsx
<Select defaultValue="weekly">
  <SelectTrigger aria-label="Frequency"><SelectValue placeholder="Pick one" /></SelectTrigger>
  <SelectContent>
    <SelectItem value="daily">Daily</SelectItem>
    <SelectItem value="weekly">Weekly</SelectItem>
  </SelectContent>
</Select>
```

## Separator

A thin horizontal or vertical divider. Decorative by default.

Install:

```bash
npx @junco/cli add separator
npx shadcn@latest add https://junco.madebytobi.com/r/separator.json
```

Exports: SeparatorProps, Separator

Props of Separator (also accepts React.HTMLAttributes<HTMLDivElement>):

- orientation?: "horizontal" | "vertical"
- decorative?: boolean. Purely visual (the default): hidden from assistive tech. Set false when it separates real sections.

## Sheet

A panel that slides in from an edge. On phones (under 640px) side sheets become bottom sheets you can swipe down to close, unless `mobileSide="same"`.

Install:

```bash
npx @junco/cli add sheet
npx shadcn@latest add https://junco.madebytobi.com/r/sheet.json
```

Exports: SheetProps, Sheet, SheetTrigger, SheetClose, sheetVariants, SheetContentProps, SheetContent, SheetHeader, SheetFooter, SheetTitleProps, SheetTitle, SheetDescription

Variants:

- side: right | left | top | bottom (default right)
- mobileSide: bottom | same (default bottom)

Props of Sheet (also accepts React.ComponentPropsWithoutRef<typeof DialogPrimitive.Root>):


Props of SheetContent (also accepts React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, VariantProps<typeof sheetVariants>):

- showClose?: boolean
- closeLabel?: string
- classNames?: { overlay?: string; content?: string; handle?: string; close?: string }

Props of SheetTitle (also accepts React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>):

- isHidden?: boolean

Usage:

```tsx
<Sheet>
  <SheetTrigger asChild><Button>Filters</Button></SheetTrigger>
  <SheetContent side="right">
    <SheetHeader><SheetTitle>Filters</SheetTitle></SheetHeader>
    ...
  </SheetContent>
</Sheet>
```

## Skeleton

A placeholder block for content that is loading. Size it with className, e.g. `h-4 w-32`.

Install:

```bash
npx @junco/cli add skeleton
npx shadcn@latest add https://junco.madebytobi.com/r/skeleton.json
```

Exports: SkeletonProps, Skeleton

Props of Skeleton (also accepts React.HTMLAttributes<HTMLDivElement>):

- isLoaded?: boolean. When true, renders `children` instead of the placeholder.

## Spinner

A loading indicator. It keeps turning (slower) with motion off, since it carries meaning.

Install:

```bash
npx @junco/cli add spinner
npx shadcn@latest add https://junco.madebytobi.com/r/spinner.json
```

Exports: spinnerVariants, SpinnerProps, Spinner

Variants:

- size: sm | md | lg (default md)

Props of Spinner (also accepts Omit<React.HTMLAttributes<HTMLSpanElement>, "children">, VariantProps<typeof spinnerVariants>):

- label?: string | null. Read by screen readers. Pass `null` when something nearby already announces the loading state.

## Stat

A single number with its label and change. Direction is shown by icon, sign and screen reader text, never by color alone.

Install:

```bash
npx @junco/cli add stat
npx shadcn@latest add https://junco.madebytobi.com/r/stat.json
```

Exports: statVariants, StatTrend, StatProps, Stat, StatGroup, SparklineProps, Sparkline

Variants:

- trend: up | down | flat (default flat)
- size: sm | md | lg (default md)

Props of Stat (also accepts Omit<React.HTMLAttributes<HTMLDivElement>, "children">, Pick<VariantProps<typeof statVariants>, "size">):

- label: React.ReactNode
- value: React.ReactNode
- delta?: number | string. Change vs the comparison period, as a number (12.5 means +12.5%) or preformatted text.
- trend?: StatTrend. Direction of the change. Inferred from a numeric delta when omitted.
- isInverse?: boolean. When a rise is bad (costs, error rate, churn), set this so "up" reads as the warning color. The icon and sign still show the real direction.
- deltaLabel?: React.ReactNode. Text after the delta, e.g. "vs last month".
- chart?: React.ReactNode. A small chart (sparkline) under the numbers. Colored with currentColor (primary by default).
- classNames?: Partial<Record<"root" | "label" | "value" | "footer" | "delta" | "deltaLabel" | "chart"

Props of Sparkline (also accepts React.SVGProps<SVGSVGElement>):

- data: number[]
- isFilled?: boolean. Fill under the line. Default true.

Usage:

```tsx
<StatGroup><Stat label="MRR" value="$48.2k" delta={4.1} /></StatGroup>
```

## Switch

An on/off toggle that applies immediately. For a choice submitted with a form, prefer Checkbox.

Install:

```bash
npx @junco/cli add switch
npx shadcn@latest add https://junco.madebytobi.com/r/switch.json
```

Exports: switchVariants, SwitchProps, Switch

Variants:

- size: sm | md | lg (default md)

Props of Switch (also accepts React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, VariantProps<typeof switchVariants>):

- classNames?: { root?: string; thumb?: string }

## Tabs

Switches between views in the same space. Variants line (page sections) and segmented (small view switchers).

Install:

```bash
npx @junco/cli add tabs
npx shadcn@latest add https://junco.madebytobi.com/r/tabs.json
```

Exports: tabsVariants, TabsProps, Tabs, TabsList, TabsTrigger, TabsContent

Variants:

- variant: line | segmented (default line)

Props of Tabs (also accepts React.ComponentPropsWithoutRef<typeof TabsPrimitive.Root>, VariantProps<typeof tabsVariants>):


Usage:

```tsx
<Tabs defaultValue="overview">
  <TabsList><TabsTrigger value="overview">Overview</TabsTrigger>...</TabsList>
  <TabsContent value="overview">...</TabsContent>
</Tabs>
```

## Textarea

A multi-line text field that can grow with its content (autoResize).

Install:

```bash
npx @junco/cli add textarea
npx shadcn@latest add https://junco.madebytobi.com/r/textarea.json
```

Exports: textareaVariants, TextareaProps, Textarea

Variants:

- size: sm | md | lg (default md)
- autoResize: true | false (default false)

Props of Textarea (also accepts React.TextareaHTMLAttributes<HTMLTextAreaElement>, VariantProps<typeof textareaVariants>):

- isInvalid?: boolean

## Toast

Brief notifications from anywhere with toast(): success, error, warning, info, loading and promise, with actions and swipe to dismiss.

Install:

```bash
npx @junco/cli add toast
npx shadcn@latest add https://junco.madebytobi.com/r/toast.json
```

Exports: ToastType, ToastId, ToastAction, ToastOptions, ToastData, ToastPromiseOptions, toast, __resetToasts, useToasts, ToasterPosition, toastVariants, ToasterProps, Toaster

Variants:

- type: default | success | error | warning | info | loading

Props of Toaster:

- position?: ToasterPosition
- visibleToasts?: number. How many toasts show at once; older ones wait behind. Default 3.
- duration?: number. Default auto-close time in ms. Default 5000.
- expand?: boolean. Always show the full stack instead of collapsing it until hover or focus.
- closeButton?: boolean. Show the × button. Default true.
- hotkey?: string[]. Keys that move focus to the toasts. Default Alt+T.
- gap?: number
- className?: string
- classNames?: Partial<Record<keyof typeof toastVariants.slots

Usage:

```tsx
toast("Saved")
toast.success("Invoice sent", { description: "Northwind will get it in a minute." })
toast.error("Couldn't save", { action: { label: "Retry", onClick: save } })
toast.promise(upload(), { loading: "Uploading…", success: "Uploaded", error: "Upload failed" })
toast.dismiss(id)
```

## Tooltip

Works without a TooltipProvider (it adds its own), but one shared provider is better.

Install:

```bash
npx @junco/cli add tooltip
npx shadcn@latest add https://junco.madebytobi.com/r/tooltip.json
```

Exports: TooltipProvider, TooltipProps, Tooltip

Props of Tooltip (also accepts Omit<React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Root>, "children">):

- content: React.ReactNode. What the tooltip says. Keep it short; never put the only copy of important info here.
- children: React.ReactElement. The element that triggers the tooltip. Must accept a ref and focus (a button, a link).
- side?: "top" | "right" | "bottom" | "left"
- align?: "start" | "center" | "end"
- sideOffset?: number
- shortcut?: string. Shown as a <Kbd>-like hint after the text, e.g. "⌘K".
- className?: string

Usage:

```tsx
<Tooltip content="Add item"><Button size="icon" aria-label="Add item">+</Button></Tooltip>
```

## Data Table

A full data table on TanStack Table: sorting, selection, search, column visibility, pagination, loading and empty states. Pass `manual` for server-side data.

Install:

```bash
npx @junco/cli add data-table
npx shadcn@latest add https://junco.madebytobi.com/r/data-table.json
```

Exports: dataTableVariants, DataTableProps, DataTable

Variants:

- density: compact | normal | relaxed (default normal)
- isStickyHeader: true (default true)

Props of DataTable (also accepts <TData>):

- columns: ColumnDef<TData
- data: TData[]
- getRowId?: (row: TData, index: number) => string. Stable row ids (recommended with selection). Defaults to the row index.
- isLoading?: boolean. Shows skeleton rows and sets aria-busy.
- loadingRows?: number. Skeleton rows while loading. Defaults to the page size (max 10).
- enableRowSelection?: boolean | ((row: TData) => boolean). Adds a checkbox column.
- rowSelection?: RowSelectionState
- onRowSelectionChange?: (selection: RowSelectionState) => void
- enableGlobalFilter?: boolean. Shows a search box that filters across all columns.
- globalFilter?: string
- onGlobalFilterChange?: (value: string) => void
- searchPlaceholder?: string
- enableColumnVisibility?: boolean. Shows a "Columns" menu to hide and show columns.
- columnVisibility?: VisibilityState
- onColumnVisibilityChange?: (visibility: VisibilityState) => void
- sorting?: SortingState
- onSortingChange?: (sorting: SortingState) => void
- defaultSorting?: SortingState
- pageSize?: number | false. Rows per page. Set `false` to show every row. Default 10.
- pageSizeOptions?: number[]
- pagination?: PaginationState
- onPaginationChange?: (pagination: PaginationState) => void
- manual?: boolean. Server-side data: sorting, filtering and paging happen outside; pass the total page count.
- pageCount?: number
- rowCount?: number. Total rows on the server, for the footer when `manual`.
- emptyState?: React.ReactNode. Shown when there are no rows.
- toolbar?: React.ReactNode. Extra controls on the right of the toolbar (filters, buttons).
- caption?: string. Accessible table name, also shown visually hidden as the caption.
- maxHeight?: string. Max height of the scroll area, e.g. "24rem". The header stays visible while scrolling.
- density?: "compact" | "normal" | "relaxed"
- isStickyHeader?: boolean
- tableOptions?: Partial<TableOptions<TData>>. Escape hatch for anything else TanStack Table supports.
- onTableReady?: (table: TanstackTable<TData>) => void. Receives the table instance (for custom toolbars or bulk actions).
- className?: string
- classNames?: Partial<Record<Slots

Usage:

```tsx
import { DataTable, type ColumnDef } from "junco/data-table";
```

## Form

React Hook Form + Zod integration: FormField wires labels, help text and errors to any Junco control.

Install:

```bash
npx @junco/cli add form
npx shadcn@latest add https://junco.madebytobi.com/r/form.json
```

Exports: FormProps, Form, FormFieldRenderProps, FormFieldProps, FormField, FormSubmit, FormRootError, useForm, useFormContext, useWatch, SubmitHandler, UseFormReturn

Props of Form (also accepts <TValues extends FieldValues> extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "onError">):

- form: UseFormReturn<TValues>. The object from `useForm()`.
- onSubmit: SubmitHandler<TValues>
- onError?: SubmitErrorHandler<TValues>

Props of FormFieldRender (also accepts <TValues extends FieldValues, TName extends FieldPath<TValues>>):

- field: ControllerRenderProps<TValues
- fieldState: ControllerFieldState
- groupProps: { "aria-labelledby": string; "aria-describedby"?: string; "aria-invalid"?: boolean }. Spread on a RadioGroup or other custom group so it is named by the label.

Props of FormField (also accepts <TValues extends FieldValues, TName extends FieldPath<TValues>> extends Omit<FieldProps, "children" | "error" | "id">):

- name: TName
- children?: React.ReactElement. A single Junco control (Input, Textarea, Select, Checkbox, Switch, RadioGroup); it gets wired up automatically. For anything else use `render`.
- render?: (props: FormFieldRenderProps<TValues, TName>) => React.ReactElement
- layout?: "stacked" | "inline". "inline" puts the label beside the control (checkboxes and switches). Default: inline for those, stacked otherwise.

Usage:

```tsx
const form = useForm<Values>({ resolver: zodResolver(schema), defaultValues });
<Form form={form} onSubmit={save}>
  <FormField name="email" label="Email"><Input type="email" /></FormField>
  <FormSubmit>Save</FormSubmit>
</Form>
```

## Theme Provider

Light, dark and system themes plus the data-motion switch, saved to localStorage, with a no-flash themeScript for SSR.

Install:

```bash
npx @junco/cli add theme-provider
npx shadcn@latest add https://junco.madebytobi.com/r/theme-provider.json
```

Exports: ThemeContextValue, ThemeProviderProps, ThemeProvider, useTheme, applyTheme, themeScript, Motion, ResolvedTheme, Theme, ThemeScriptOptions

Props of ThemeProvider:

- children?: React.ReactNode
- defaultTheme?: Theme. Used until the user picks one. Default "system".
- defaultMotion?: Motion. Default "full". `prefers-reduced-motion` always turns motion off regardless.
- theme?: Theme. Controlled theme. When set, the provider never writes storage for the theme.
- motion?: Motion. Controlled motion.
- onThemeChange?: (theme: Theme) => void
- onMotionChange?: (motion: Motion) => void
- storageKey?: string. localStorage key prefix. Default "junco". Stores `<key>-theme` and `<key>-motion`.

## Theme Script

An inline script for <head> that applies the saved theme before first paint, so server-rendered pages don't flash light then dark. Use it with the same options you pass to ThemeProvider.

Install:

```bash
npx @junco/cli add theme-script
npx shadcn@latest add https://junco.madebytobi.com/r/theme-script.json
```

Exports: Theme, ResolvedTheme, Motion, DARK_QUERY, ThemeScriptOptions, applyTheme, themeScript

Usage:

```tsx
<script dangerouslySetInnerHTML={{ __html: themeScript() }} />
```