# Koala UI

> A commercial React design system: 123 components built on Tailwind CSS v4, Radix UI and
> tailwind-variants, with four themes (light, cream, dark, moonlight), eight accents and a
> two-step density axis, all flowing from one layer of semantic CSS variables. The CLI copies the
> source into your repo, so you own it; there is no runtime package to be locked into.

## Conventions

- Multi-part components use `tv` with `slots`; there is no `cva` in this codebase.
- Parts are NAMED exports, never dot-notation: `Card`, `CardHeader`, `CardBody`. Namespaced
  statics do not survive the RSC server-to-client boundary.
- Cross-part state flows through React Context (`lib/create-context.tsx`), never by cloning
  children.
- Colors, radii, shadows and motion come from tokens. No raw hex, `oklch()`, `cubic-bezier()`
  or millisecond literals inside a component.
- Every component accepts `className`, merged last through `tailwind-merge`.
- React 19: `ref` is a regular prop, so there is no `forwardRef`.

## Install and update

```bash
npx koalaui-cli@latest init                       # once: tokens, lib helpers, theme provider, base deps
npx koalaui-cli@latest add button card dialog     # components, their dependencies pulled along
npx koalaui-cli@latest list                       # everything available, free and Pro
npx koalaui-cli@latest diff [item]                # what changed upstream since you installed
npx koalaui-cli@latest update [item] [--force]    # replace untouched files; edited files are kept
npx koalaui-cli@latest template <name> [dir]      # Pro: start a whole site from a template
npx koalaui-cli@latest skill                      # write the Koala agent skill into .claude/skills/koala-ui
```

`init` writes `koala.css` and imports it from the stylesheet that imports Tailwind. In Next.js
that is `app/globals.css`, and the root layout then loads Inter as `--font-sans` and DM Sans as
`--font-heading` with `next/font`. In Vite it is `src/index.css` (tokens in `src/styles/koala.css`),
and `init` wires both faces itself from `@fontsource-variable`. Either way the app is wrapped in
the `ThemeProvider` from `components/theme-provider.tsx` (themes: light, cream, dark, moonlight;
`forcedTheme` pins one). Components land in `components/ui/<name>/` (under `src/` in Vite) and
import through the `@/*` path alias. `add` refuses while a flat shadcn/ui file of the same name
would shadow a Koala folder. Every install is recorded in `koala.json`, which is how `diff` and
`update` know what you edited.

## Free and Pro

- Free, no account: all 123 components, the lib helpers and the design tokens.
  Their docs, code included, are below.
- Pro, with a license: every section, the page examples and the templates.
  Activate a key once per machine with `npx koalaui-cli@latest login <key>`, then add Pro items like free ones.
  Licenses: https://www.koalaui.com/pro. A section page's markdown names its Pro variants and stops there:
  their source is never published in these docs.

## Docs for agents

- Every docs page has a markdown twin at its URL plus `.md`, and every link below points at one.
- [llms-full.txt](https://www.koalaui.com/llms-full.txt): every free docs page (guides, foundations, components) in one file.
- The Koala UI agent skill: `npx koalaui-cli@latest skill` writes it to `.claude/skills/koala-ui/`, one reference per component.
- [AI and agents](https://www.koalaui.com/docs/agents.md): how to use all of this with Claude Code, Cursor and ChatGPT.

## Getting Started

- [Introduction](https://www.koalaui.com/docs.md): The React implementation of Koala UI, built on Next.js, Tailwind v4, Radix, and tailwind-variants.
- [Installation](https://www.koalaui.com/docs/installation.md): Add Koala UI to your React app. Run the one-time setup, wire the fonts and theme into your layout, add the components you need, and pull updates later without losing your edits.
- [Architecture](https://www.koalaui.com/docs/architecture.md): The house style for building Koala UI - a pragmatic distillation of modern React design-system patterns, taking what scales and dropping what's clever-but-fragile.
- [Patterns](https://www.koalaui.com/docs/patterns.md): Component decision guide - when to reach for which piece, with live examples of each pattern in context.
- [AI and agents](https://www.koalaui.com/docs/agents.md): Koala's docs are built for coding agents too: every page as markdown, an llms.txt index, the whole docs in one file, and a skill that teaches an agent Koala's rules. How to use each.
- [From shadcn/ui](https://www.koalaui.com/docs/migrating-from-shadcn.md): Most of what you know from shadcn/ui carries over: Radix underneath, Tailwind, the source in your repo. Here is every shadcn component's Koala counterpart, and every name that changes.

## Foundations

- [Theming](https://www.koalaui.com/docs/foundations/theming.md): Koala is themed entirely through CSS variables. Components read semantic tokens, never a raw color, radius or shadow, so one block of variables restyles the whole system.
- [Colors](https://www.koalaui.com/docs/foundations/colors.md): Koala's color system is three layers deep: a literal value, the CSS variable that holds it, and the semantic token a component writes. Components only ever reach for the top layer.
- [Typography](https://www.koalaui.com/docs/foundations/typography.md): Two typefaces: Inter carries UI and body copy, DM Sans the headings, with the system monospace as the code fallback. The scale, weights, tracking and leading come straight from Tailwind v4.
- [Spacing & Layout](https://www.koalaui.com/docs/foundations/spacing.md): Spacing and container widths are Tailwind v4 defaults, used as-is, with one addition (--container-8xl, 1440px) kept as an opt-in escape above the canonical 1280px section cap.
- [Breakpoints](https://www.koalaui.com/docs/foundations/breakpoints.md): The five responsive thresholds Koala builds on: Tailwind v4 defaults, used verbatim. Styles are mobile-first: an unprefixed utility applies everywhere, a prefixed one applies from that width up.
- [Density](https://www.koalaui.com/docs/foundations/density.md): Density is the cross-cutting knob that retunes padding, gaps and control heights without touching color or radius. comfortable is the marketing-first default; compact is the application-UI preset.
- [Radius & Shadows](https://www.koalaui.com/docs/foundations/surfaces.md): The surface foundation. Radius is driven by a single --radius knob, so the whole scale re-rounds from one value. Shadows carry per-theme values so dark surfaces stay legible.
- [Aspect Ratio](https://www.koalaui.com/docs/foundations/aspect-ratio.md): The shapes media is framed in. Koala uses Tailwind's aspect-* utilities as-is: pick the ratio on the frame, let the image crop to fill it, and the layout holds its shape before the pixels arrive.
- [Motion](https://www.koalaui.com/docs/foundations/motion.md): Three easing curves and three durations, exposed as Tailwind utilities and mirrored in lib/motion.ts for JS animation. Never inline a raw cubic-bezier or ms value.
- [Morphing](https://www.koalaui.com/docs/foundations/morphing.md): A surface that changes what it shows eases to its new size while its contents crossfade inside, so the eye follows one object instead of watching one leave and another arrive.
- [Fade](https://www.koalaui.com/docs/foundations/scroll-fade.md): A soft mask that dissolves a box into its surface at its edges. Use the static fade-* utilities for a constant bleed, or the scroll-fade-* siblings to track scroll position. Pure CSS, no JS.
- [Icons](https://www.koalaui.com/docs/foundations/icons.md): Phosphor Icons - a flexible, MIT-licensed family with 6 weights per glyph and over 1 400 icons. Always import from /ssr in Server Components; the bare import is for 'use client' files only.
- [File Icons](https://www.koalaui.com/docs/foundations/file-icons.md): File-type icons as pure inline SVG: a sheet with a folded corner and the extension, toned by category. Three variants, four sizes, and every icon ready to copy or download.
- [Flags](https://www.koalaui.com/docs/foundations/flags.md): 261 country and region flags as pure inline SVG, in three shapes and six sizes. Search the set, pick a shape, and copy or download any flag as a standalone SVG.
- [Logos](https://www.koalaui.com/docs/logos.md): Placeholder brand logos: fictional companies, each a colored symbol beside an invented wordmark, plus a small set of real marks. Pure inline SVG, no binary assets.

## Marketing / Components

- [Announcement](https://www.koalaui.com/docs/components/announcement.md): The pill above a hero title: a standing label paired with the thing being announced. Single-element like Badge, and it nests a Badge for the announced half without drawing a second border around it.
- [Banner](https://www.koalaui.com/docs/components/banner.md): A full-bleed announcement bar for promos, release notes and site-wide notices. Soft tones tint the background, message, icon and action from one semantic token, so the whole bar reads as a single hue.
- [Bento](https://www.koalaui.com/docs/components/bento.md): An asymmetric marketing grid of feature tiles. Named parts you assemble: a tinted icon, a balanced title, a description and a media region. Each tile claims a size and a tone, and the grid collapses to one column.
- [FAQs](https://www.koalaui.com/docs/components/faqs.md): A marketing-ready frequently-asked-questions section built on the Accordion. It pairs a header with a single-expand question list and an optional contact CTA, in a centered stack or a sticky two-column split.
- [Footer](https://www.koalaui.com/docs/components/footer.md): A composable site footer for marketing, product and ecommerce pages. Pure layout: a brand column plus grouped link columns up top, and a bottom bar with copyright, legal links and social icons.
- [Gallery](https://www.koalaui.com/docs/components/gallery.md): A marketing concepts wall: a balanced headline and lead, an optional tab rail to switch template categories, and a full-bleed fake-masonry of framed preview tiles. Our own Tabs, plus plain CSS columns.
- [Hero](https://www.koalaui.com/docs/components/hero.md): A centered marketing hero section. Named parts you assemble: an announcement eyebrow, a balanced headline, a subtitle, a CTA row, a check-circle feature list and an integrated social-proof row.
- [Job Card](https://www.koalaui.com/docs/components/job-card.md): The canonical open-role block: a category badge, the role title, a one-line summary and a meta tier of location, employment type and salary band. Renders as a chrome-less row or a bordered card.
- [Navbar](https://www.koalaui.com/docs/components/navbar.md): A composable top navigation bar for marketing, product and ecommerce shells. Layout is composition, not configuration: a NavbarSpacer pushes groups apart. Collapses to a hamburger disclosure below md.
- [Pricing](https://www.koalaui.com/docs/components/pricing.md): A responsive marketing pricing table. Named parts you assemble into plan cards: a name, a big tabular price, a feature checklist and a bottom-pinned call to action. Mark the recommended plan featured.
- [Pricing Comparison](https://www.koalaui.com/docs/components/pricing-comparison.md): A feature-by-feature pricing matrix: rows are features, columns are plans, and each cell is a check, a minus or a value. Group rows into sections, highlight the recommended plan, and hang a tooltip off any row.
- [Section](https://www.koalaui.com/docs/components/section.md): The content half of every marketing section: a full-bleed band and a centered 1280px gutter with a canonical gap to the content below. Pair it with SectionHeader and every block shares one rhythm.
- [Section Header](https://www.koalaui.com/docs/components/section-header.md): The lede every section opens with: a Badge eyebrow, a balanced heading, a supporting paragraph and a CTA row. Two axes, align and orientation, recompose it, so every block on the page shares one rhythm.
- [Team Member](https://www.koalaui.com/docs/components/team-member.md): The person block of a team roster: a photo frame, the name, the role, an optional bio and a row of social links. Stacked, inline or set over the photo, as a plain block or an outline card.
- [Testimonials](https://www.koalaui.com/docs/components/testimonials.md): A minimal quote card for social-proof walls. Named parts you assemble: an optional quote mark, the quote, an author row and an optional logo. Stars come from Rating, the headshot from Avatar.

## Marketing / Sections

- [Hero](https://www.koalaui.com/marketing/sections/hero.md): The opening section of a landing page. Twenty-two finished layouts, from the product hero over a bleeding component collage and realistic device shots to full-bleed media, scroll stages and editorial openings.
- [Header](https://www.koalaui.com/marketing/sections/header.md): The opening of an inner page: its one H1, a lede and what to do next, at a third of a hero's height. Nine headers, from a centered title to a search field, a brand band, a photo banner and a document header.
- [Social Proof](https://www.koalaui.com/marketing/sections/social-proof.md): The logo-led trust band: customer logos that tell a visitor who already builds on the product. Pick the airy cloud, an infinite marquee, a bordered grid, an editorial split, or a bento with a featured story.
- [Feature](https://www.koalaui.com/marketing/sections/feature.md): Sections that show what the product does. Twenty-five layouts, from a wall of live interactive tiles and asymmetric bento grids to capability columns, dark bands with bleeding product shots and tab-switched screens.
- [Gallery](https://www.koalaui.com/marketing/sections/gallery.md): Marketing image walls built on Gallery and Lightbox: a tabbed fake-masonry, a two-direction marquee, a ring of frames that orbits as you scroll, a click-through story, a spotlight rail and customer walls.
- [Portfolio](https://www.koalaui.com/marketing/sections/portfolio.md): The our-work family: five ways for a studio or an agency to show what it has shipped. A scannable work index, alternating case-study rows, a card grid behind a load-more fade, a stills lightbox, and a slideshow.
- [Testimonials](https://www.koalaui.com/marketing/sections/testimonials.md): Finished testimonial sections: a minimal author-led row, a logo-led row, a spotlight carousel with a portrait beside the quote, a full masonry wall clamped by a load-more, and one voice beside a wide picture.
- [Team](https://www.koalaui.com/marketing/sections/team.md): The people behind the product, eight ways: a portrait grid, a wall of faces, a rail that runs off the page, cards with bios, a compact directory, round portraits, a sticky split and the whole company drifting past.
- [Stats](https://www.koalaui.com/marketing/sections/stats.md): Proof, counted. Ten ways to turn coverage, adoption and outcomes into a band of figures, from a bare ruled row to an elevated inverse panel and a mixed grid of numbers and voices.
- [Pricing](https://www.koalaui.com/marketing/sections/pricing.md): Two ways to price a product: the three-plan table with a highlighted tier, tabular prices and a feature checklist on each card, and the comparison that lays every feature out row by row under the same plans.
- [FAQ](https://www.koalaui.com/marketing/sections/faq.md): The product's common questions as a finished section, from a plain accordion to a full help centre: grouped lists, sticky split ledes, topic rails, searchable boards, chips beside a photograph, and tile grids.
- [Changelog](https://www.koalaui.com/marketing/sections/changelog.md): The release log, in eight layouts: a timeline of version cards, a vertical ActivityFeed rail, a row of media cards, a minimal editorial two-column list, a bare date-led notes list, the full release notes a changelog page needs, a pill-filtered thread, and a month-grouped log beside a checkbox filter rail.
- [Blog](https://www.koalaui.com/marketing/sections/blog.md): Editorial indexes for a company blog or resource hub. Five layouts: a filtered featured grid, a minimal text-first list, a lead-plus-latest rail, an image-led magazine grid and a date-led archive list.
- [Careers](https://www.koalaui.com/marketing/sections/careers.md): Eleven ways to publish an open-roles board, every one a composition of Job Card over the same dataset: a dense table, chrome-less rows, card grids behind a search or a team filter, rails, and a categorised list.
- [CTA](https://www.koalaui.com/marketing/sections/cta.md): Calls to action, from a quiet mid-page nudge to a bold closing band. Fifteen layouts: brand-lit panels, inline email capture, device-led product shots, oversized typographic statements and full-bleed photographs.
- [Contact](https://www.koalaui.com/marketing/sections/contact.md): Contact and lead-capture sections that pair a marketing message with a way to reach you: a split lead capture over an interior photo, a channel list beside a form, a centered lede, and a department directory.
- [Legal](https://www.koalaui.com/marketing/sections/legal.md): The body of a terms, privacy or license page, set as reading type: one narrow column of numbered clauses, or the same text with its table of contents pinned beside it and the clause in view marked.
- [Status](https://www.koalaui.com/marketing/sections/status.md): The pages a visitor lands on when something is missing, broken or not ready: three not-found pages, a server error, a maintenance window, a coming-soon page, a waitlist confirmation and the status page itself.
- [Banner](https://www.koalaui.com/marketing/sections/banner.md): A full-bleed announcement bar for promos, release notes and site-wide notices. Soft tones tint a background while the icon and action carry the hue. Sits above the navbar or atop any page region.
- [Footer](https://www.koalaui.com/marketing/sections/footer.md): The closing section of a page. Five finished layouts: the classic brand column with grouped links, a full-bleed image overlay, a newsletter strip over a link grid, a newsletter card, and a minimal centered footer.
- [Navbar](https://www.koalaui.com/marketing/sections/navbar.md): The bar at the top of a page. Six finished layouts: the conventional marketing bar, one with full-height tabs, a floating island, an editorial storefront, a compact app toolbar, and a dark floating capsule.

## Marketing / Pages

- [Landing](https://www.koalaui.com/marketing/pages/landing.md)
- [Features](https://www.koalaui.com/marketing/pages/features.md)
- [Pricing](https://www.koalaui.com/marketing/pages/pricing.md)
- [About](https://www.koalaui.com/marketing/pages/about.md)
- [Customers](https://www.koalaui.com/marketing/pages/customers.md)
- [Careers](https://www.koalaui.com/marketing/pages/careers.md)
- [Portfolio](https://www.koalaui.com/marketing/pages/portfolio.md)
- [Blog](https://www.koalaui.com/marketing/pages/blog.md)
- [Blog post](https://www.koalaui.com/marketing/pages/blog-post.md): Full, ready-to-ship article pages: navbar, header, cover, long-form body, author, related posts and footer. Three layouts share one article: a cover-led classic, a sticky table of contents, and an image-led hero.
- [Changelog](https://www.koalaui.com/marketing/pages/changelog.md)
- [Contact](https://www.koalaui.com/marketing/pages/contact.md)
- [FAQ](https://www.koalaui.com/marketing/pages/faq.md)
- [Legal](https://www.koalaui.com/marketing/pages/legal.md)
- [Status](https://www.koalaui.com/marketing/pages/status.md)

## Application UI / Components / AI

- [AI Panel](https://www.koalaui.com/docs/components/ai-panel.md): The assistant sidepanel: a header, a scrollable conversation and a pinned composer in one column. Drop a Chat in the body and a Prompt Input in the footer. Pure layout, so it docks in a page or drops into a Drawer.
- [Chat](https://www.koalaui.com/docs/components/chat.md): The AI conversation thread, the second piece of the AI module. The assistant answers as a document, the Notion and ChatGPT style; the user turn stays a bubble. Streaming and reasoning included.
- [Generation](https://www.koalaui.com/docs/components/generation.md): The card a model fills while it paints a picture. The frame is sized by its ratio before there is anything to put in it, so nothing jumps, and the picture comes in from the top out of a halftone field of dots.
- [Plan](https://www.koalaui.com/docs/components/plan.md): The card an assistant hands you before it acts: what it intends to do, as a short list of to-dos you can read, edit and approve. Deliberately quiet, so status lives in a small mark at the head of each row.
- [Prompt Input](https://www.koalaui.com/docs/components/prompt-input.md): The AI composer: an auto-growing textarea with a built-in toolbar and a send or stop button. Wire onSubmit once and the textarea, model picker, count and submit stay in sync through context.
- [Suggestions](https://www.koalaui.com/docs/components/suggestions.md): Inline AI edit suggestions over a body of text. The AI marks spans with a colored dotted underline; click one to see the proposed replacement and a reason, then apply it in place or dismiss it.

## Application UI / Components / Forms

- [Authentication](https://www.koalaui.com/docs/components/auth-form.md): The sign-in and sign-up pair, shipped as two ready blocks: social providers, an email and password core, and the cross-link to its sibling. Sign-up adds a name field and a live password-strength meter.
- [Contact](https://www.koalaui.com/docs/components/contact-form.md): A family of ready get-in-touch blocks on one recipe: ContactForm, LeadForm for sales, and SupportForm for help-desk requests. Each wires its controls through Field, owns its state and confirms on submit.
- [Feedback](https://www.koalaui.com/docs/components/feedback-form.md): A compact sentiment and comment block. A row of five faces reveals an optional comment field once one is picked, then submits. It owns its rating and message state; wire onSubmit to your sink.
- [Newsletter](https://www.koalaui.com/docs/components/newsletter-form.md): A ready-to-ship email-capture block. It owns its own email state, validates the address and runs the loading to success flow. Two layouts: a self-contained card and a single-row inline signup.
- [Payment](https://www.koalaui.com/docs/components/payment-form.md): A complete card-checkout block. The number, expiry and CVC are masked as you type, the card brand is detected live, and the billing country shows circular flags. Accept promo codes to roll the total.
- [Settings](https://www.koalaui.com/docs/components/settings-form.md): An account-profile editing block: an avatar with change and remove controls, a name row, a prefixed username, email and a bio with a live count, closed by a Cancel and Save footer.
- [Survey](https://www.koalaui.com/docs/components/survey.md): Google-Forms-style question cards: an eyebrow, a title with an optional required asterisk, and an answer. Survey owns the layout and semantics; the controls are the real DS components.
- [Waitlist](https://www.koalaui.com/docs/components/waitlist-form.md): A centered waitlist block: a headline, a one-row email capture and a social-proof footer with overlapping avatars and a running count. On submit it flips to a confirmed state; wire onJoin to your list.

## Application UI / Components / Data Display

- [Animated Label](https://www.koalaui.com/docs/components/animated-label.md): Text that rolls when it changes state: the outgoing label lifts out while the incoming one rises from below, and the box eases between the two widths. The prose sibling of Animated Number: Next to Done, Weak to Strong.
- [Animated Number](https://www.koalaui.com/docs/components/animated-number.md): A figure that rolls when it changes, one character at a time: each changed digit lifts out while its replacement rises from below. Backed by the motion tokens and tabular-nums, so the width never jumps.
- [Chart](https://www.koalaui.com/docs/components/chart.md): A dependency-free plotting primitive for trends, funnels and pies. Compose the named parts into one measured SVG; the legend focuses and toggles series, and every hue re-themes.
- [Data Table](https://www.koalaui.com/docs/components/data-table.md): A data grid built on TanStack Table for behavior (sorting, grouping, row selection, column pinning) with Koala styling on top. Drive features from column defs, or compose the styled primitives directly.
- [Description List](https://www.koalaui.com/docs/components/description-list.md): A semantic key/value detail view for records: profiles, invoices, settings read-outs. It renders a real dl/dt/dd tree, splits term and value at sm, and any value cell composes Koala parts like Badge or Avatar.
- [Heatmap](https://www.koalaui.com/docs/components/heatmap.md): A grid of cells tinted by value, for activity by hour, a year of days or a retention cohort. Scale it per grid, row or column; every cell reads out on hover, on focus and to screen readers.
- [Order Summary](https://www.koalaui.com/docs/components/order-summary.md): The checkout and cart order read-out. One composable card that stacks line items, a promo-code band and a totals breakdown, with every price on tabular-nums so the column never jitters.
- [Ranking](https://www.koalaui.com/docs/components/ranking.md): A leaderboard card for the tops of a dashboard: products, customers or countries. Read it as stacked rows or a vertical bar chart, each row carrying a position chip, a value and a relative-share bar.
- [Stat](https://www.koalaui.com/docs/components/stat.md): A KPI/metric card for dashboards: a label, a big tabular-nums value, a directional trend chip, and optional icon or sparkline. Compose the named parts into a tile, then drop a row of them above a Data Table.

## Application UI / Components / Base

- [Accordion](https://www.koalaui.com/docs/components/accordion.md): A stack of disclosure rows built on Radix Accordion: keyboard nav, ARIA, and single or multiple expansion. The variant axis spans a flush minimal list, contained cards, a pill list that hugs its own text, and a board grid.
- [Activity Feed](https://www.koalaui.com/docs/components/activity-feed.md): A vertical timeline of what happened: comments, mentions, status changes, uploads, members joining. One rail threads every event, while each row varies its marker and its body, from a terse audit log to a rich inbox.
- [Alert](https://www.koalaui.com/docs/components/alert.md): An inline status banner for page-level messages, validation summaries, and contextual feedback. Five semantic variants, optional icon, actions, and a dismiss button.
- [Avatar](https://www.koalaui.com/docs/components/avatar.md): Represents a user with an image, initials fallback, and optional presence status. Multi-part over Radix Avatar; size and shape flow to every part through Context.
- [Avatar Group](https://www.koalaui.com/docs/components/avatar-group.md): An overlapping stack of avatars with built-in overflow. Cap how many show and the rest fold into a +N chip. The group owns the overlap, the ring separation and the hover lift; the children stay plain Avatars.
- [Badge](https://www.koalaui.com/docs/components/badge.md): A compact label for status, counts, and categories. Single-element like Button; status variants are soft tints derived from semantic tokens, so they re-theme everywhere.
- [Badge Group](https://www.koalaui.com/docs/components/badge-group.md): A cluster of badges with built-in overflow. Cap how many show inline and the rest fold into a +N chip that reveals the full list in a tooltip, so a long set of tags never blows out its row.
- [Breadcrumb](https://www.koalaui.com/docs/components/breadcrumb.md): Shows the user's location within a site hierarchy. A multi-part navigation landmark built from semantic HTML with no shared state between parts.
- [Button](https://www.koalaui.com/docs/components/button.md): Triggers an action or event. The reference single-element component: one tv recipe, Radix Slot for asChild, semantic tokens only.
- [Button Group](https://www.koalaui.com/docs/components/button-group.md): A set of related buttons arranged as a visual unit. Supports attached (fused pill) and detached (spaced) layouts, with shared variant, size, and density propagated via context.
- [Card](https://www.koalaui.com/docs/components/card.md): A surface that groups related content. The reference multi-part component: one tv recipe with slots, shared variants flowing to every part through React Context.
- [Carousel](https://www.koalaui.com/docs/components/carousel.md): A horizontal slide viewer with a clickable indicator. The track translates between full-width slides, arrow keys step it, and the indicator ships with a closed set of forms: dots, lines, fraction, thumbnails.
- [Checkbox](https://www.koalaui.com/docs/components/checkbox.md): A control for a binary or tri-state choice, built on Radix Checkbox. Supports the indeterminate state a “select all” needs. It's the same control the DataTable uses for row selection.
- [Checklist](https://www.koalaui.com/docs/components/checklist.md): The onboarding panel: a card that tracks a short list of setup tasks and their progress. The bar and the 3-of-6 read-out derive from value and total, and the bar turns green the moment every step is done.
- [Code Snippet](https://www.koalaui.com/docs/components/code-snippet.md): A polished code block: rounded surface, optional window chrome, copy-on-hover, line numbers and token-driven highlighting. The highlighter is a small, dependency-free tokenizer for TS/TSX, shell and CSS.
- [Collapsible](https://www.koalaui.com/docs/components/collapsible.md): One region that opens under its trigger: show more, advanced settings, the log behind an error. No chrome of its own, a height tween on the system's motion tokens, and a mark that turns rather than swaps.
- [Color Picker](https://www.koalaui.com/docs/components/color-picker.md): A full HSV color picker in one panel: a HEX/HSL/RGB switcher, a draggable saturation square, hue and alpha rails, channel fields, an eyedropper and a preset palette. The rails ride Radix Slider for keyboard and ARIA.
- [Command](https://www.koalaui.com/docs/components/command.md): A searchable command palette: the Cmd-K menu. Arrows move the highlight, Enter runs the active row, and focus never leaves the input. Built on Radix Dialog; filtering and the roving highlight are hand-rolled.
- [Context Menu](https://www.koalaui.com/docs/components/context-menu.md): The actions menu that opens where you right-click. Built on Radix ContextMenu for keyboard navigation and a11y; it shares its surface and density with Dropdown Menu, but anchors to the cursor.
- [Cookie Consent](https://www.koalaui.com/docs/components/cookie-consent.md): A GDPR-ready consent surface in two coordinated pieces over one shared state: a non-blocking banner and a preferences dialog with a toggle per cookie category. The parts are the real DS components.
- [Date Picker](https://www.koalaui.com/docs/components/date-picker.md): A calendar surface plus two ready pickers, single date and range, over Radix Popover with native Date math and no date dependency. Selection reads the brand accent; the in-range fill stays neutral.
- [Dialog](https://www.koalaui.com/docs/components/dialog.md): A modal window over the page. Built on Radix Dialog for focus trap, scroll lock, and a11y; styled with one tv slots recipe and animated with interruptible enter/exit.
- [Divider](https://www.koalaui.com/docs/components/divider.md): A thin rule that separates content, optionally with a centered label. Smart by default: it collapses when it would be orphaned, so a dynamic list never leaves a rule at the edge or over an empty state.
- [Dock](https://www.koalaui.com/docs/components/dock.md): A floating rail of icon controls that morphs, in place, into a labelled menu with drill-down layers. One box animates its own width, height and corner, so the rail becomes the menu instead of opening a second surface.
- [Drawer](https://www.koalaui.com/docs/components/drawer.md): A panel that slides in from any edge of the screen. Built on Radix Dialog for focus trap, scroll lock and a11y; tuned for mobile with full-bleed side panels, a bottom-sheet grab handle, and swipe-to-dismiss.
- [Dropdown Menu](https://www.koalaui.com/docs/components/dropdown-menu.md): A contextual menu that opens on trigger. Built on Radix DropdownMenu for keyboard navigation, focus management, and a11y; animated with interruptible enter/exit transitions.
- [Emoji Picker](https://www.koalaui.com/docs/components/emoji-picker.md): A complete picker: searchable, with a scroll-spy category nav, a pinned frequently-used row, persisted recents and a hovered preview. Categories mount lazily, so a large set never paints at once.
- [Empty State](https://www.koalaui.com/docs/components/empty-state.md): The zero-data, no-results and first-run placeholder. A neutral icon tile, a balanced title, a readable description and a single outline action, composed from named parts, with a density axis for in-panel use.
- [Expandable Search](https://www.koalaui.com/docs/components/expandable-search.md): A search that rests as an icon button and grows into a full field on click. One box widens under the magnifier, so the glyph never moves and the open field is the DS Input, pixel for pixel.
- [Field](https://www.koalaui.com/docs/components/field.md): The wrapper that turns any control into a labelled form field. Field generates the id, htmlFor and aria-describedby wiring for you and cascades error and disabled state to the control inside.
- [File Card](https://www.koalaui.com/docs/components/file-card.md): A card for a single file: a realistic file-type illustration or image thumbnail, the name, a meta line, trailing actions and an optional progress bar. Composes into attachment rows and upload trays.
- [File Preview](https://www.koalaui.com/docs/components/file-preview.md): Look at a file where it is instead of opening another tab. PDFs page through with selectable text, images zoom and pan, and one set of controls fits, zooms, rotates and pages every kind.
- [File Upload](https://www.koalaui.com/docs/components/file-upload.md): The uploading experience: a drag-and-drop dropzone, a browse trigger, import shortcuts and built-in accept, size and count validation. Pairs with File Card for the resulting rows and per-file progress.
- [Form](https://www.koalaui.com/docs/components/form.md): The anatomy layer above Field. Field solves one labelled control; Form owns everything around them: the form element and its rhythm, the chapters of a long form, the fieldset, and the bar that closes it.
- [Hover Card](https://www.koalaui.com/docs/components/hover-card.md): A preview that opens while the pointer rests on a link: the profile behind a mention, the page behind a link, the commit behind a hash. Popover's surface, grown out of the link it previews.
- [Input](https://www.koalaui.com/docs/components/input.md): A compound text field with a label, optional hint, prefix icons, suffix icons, prefix labels, and interactive suffix buttons. Built with slots and Context - each part is a named export.
- [Input Group](https://www.koalaui.com/docs/components/input-group.md): Joins several controls, a field, a Select, a static affix, a small icon-only action, into one seamless segmented shell. The group owns the border and focus ring; each segment goes chromeless and melts in.
- [Island](https://www.koalaui.com/docs/components/island.md): A floating pill that changes with what the viewer is doing. Each state is a view, and switching views morphs the pill to its new size while the contents crossfade in place.
- [Kbd](https://www.koalaui.com/docs/components/kbd.md): A keyboard key indicator for documenting shortcuts. Renders a native <kbd>; the default variant is a flat gray chip (no border, no shadow) that re-themes everywhere. Compose combos by placing several side by side.
- [Label](https://www.koalaui.com/docs/components/label.md): The one label and helper-text recipe behind every form control in Koala. Input, Field and OTP Input all compose Label and Hint, and inside a Field they auto-wire their own ids, htmlFor and aria.
- [Layout](https://www.koalaui.com/docs/components/layout.md): The application and page shell. One set of parts and two app shells that share it: plain, the classic rail-and-content layout, and docked, the default, a black frame with the content set into it.
- [Link](https://www.koalaui.com/docs/components/link.md): The text link, in both house treatments. default and muted are the standalone UI link for chrome, warming to the brand accent on hover; prose is the hyperlink embedded in running copy, underlined at rest.
- [Lightbox](https://www.koalaui.com/docs/components/lightbox.md): A full-screen, browsable image viewer over Radix Dialog. Give it the image list once and any LightboxTrigger opens it at that index. Page between images with arrow buttons, arrow keys and a thumbnail rail.
- [List](https://www.koalaui.com/docs/components/list.md): The canonical vertical list group: stacked rows with leading media, a title and description, and trailing meta or actions. Rows are inert by default and become links or buttons via asChild.
- [Load More](https://www.koalaui.com/docs/components/load-more.md): Clamps a long region to a couple of rows, fades its cut edge, and puts one reveal button under it. The fade is a mask, not a painted gradient, so it works unchanged on any surface.
- [Menubar](https://www.koalaui.com/docs/components/menubar.md): The File, Edit, View row of a desktop-style app. One tab stop, arrow keys across the menus, and once one is open the next opens on hover. The menus are Dropdown Menu's panels, so both read as one object.
- [Multi Select](https://www.koalaui.com/docs/components/multi-select.md): A select that picks many values and stays open while you toggle them. Radix Select closes on pick, so this is built on Radix Popover instead, matching Select's surface with a checkbox or switch per row.
- [Native Select](https://www.koalaui.com/docs/components/native-select.md): The browser's own select, dressed as Koala's Select trigger. The list that opens is the operating system's: the wheel on iOS, the sheet on Android. Closed, it is indistinguishable from a Select of the same size.
- [Navigation Menu](https://www.koalaui.com/docs/components/navigation-menu.md): Menus that open on hover and share one floating panel, so moving between triggers resizes and slides the same surface instead of opening a new popover.
- [OTP Input](https://www.koalaui.com/docs/components/otp-input.md): A numeric one-time-passcode field. Auto-advances on entry, distributes pasted codes across slots, and supports SMS autofill on mobile. Configure the digit count, size, and error state with plain props.
- [Pagination](https://www.koalaui.com/docs/components/pagination.md): A toolbar for navigating a paged dataset: current page and total, prev/next, a go-to-page field and a rows-per-page select. Each addon is toggled by a show* boolean, from a bare bar to a full footer.
- [Password Strength](https://www.koalaui.com/docs/components/password-strength.md): A live strength meter for password fields: a segmented bar that climbs red to green, a one-word verdict and an optional requirements checklist. It scores the value against a rule set you control.
- [Popover](https://www.koalaui.com/docs/components/popover.md): A general-purpose floating surface over Radix Popover: focus management, dismiss and collision-aware positioning. Hosts forms, pickers and info cards, with an exposed --surface so nested controls blend in.
- [Progress](https://www.koalaui.com/docs/components/progress.md): A bar that reports how far along something is. Built on Radix Progress, so the value is announced to assistive tech for free. The label and readout are droppable parts, and a chrome variant strips the track.
- [Promo Card](https://www.koalaui.com/docs/components/promo-card.md): The in-app feature promotion for dashboards: a product eyebrow, a short pitch and one quiet action, beside a framed peek of the feature that runs off the card's edge and dissolves into it.
- [Prose](https://www.koalaui.com/docs/components/prose.md): The reading type. Wrap a document, CMS rich text, rendered Markdown or plain JSX, and its bare headings, lists, quotes, code and tables are typeset on Koala's tokens, with one size prop.
- [QR Code](https://www.koalaui.com/docs/components/qr-code.md): A QR code rendered as crisp, dependency-free SVG. The matrix is generated in-house, byte mode, ECC levels L through H, with automatic version and mask selection, and paints in the current text color.
- [Radio Group](https://www.koalaui.com/docs/components/radio-group.md): A set of mutually exclusive options where exactly one can be selected, built on Radix RadioGroup. Sizes line up pixel-for-pixel with Checkbox, so radios and checkboxes sit flush in the same form.
- [Rating](https://www.koalaui.com/docs/components/rating.md): A 1-to-N star rating built on Radix RadioGroup: roving focus, arrow keys and hover preview for free. Active stars render solid, the one place the DS opts out of its outline-only rule, and half stars read cleanly.
- [Resizable](https://www.koalaui.com/docs/components/resizable.md): Split a surface into panels the user can drag to resize. No Radix primitive ships this, so the handle is hand-rolled: it carries role=separator, is arrow-key operable, and reports through aria-valuenow.
- [Rich Text Editor](https://www.koalaui.com/docs/components/rich-text-editor.md): A WYSIWYG editor for formatted prose: headings, bold, italic, underline, links and lists. Built on Tiptap for selection, undo and paste, with every pixel of UI owned as a Koala tv recipe.
- [Scroll Area](https://www.koalaui.com/docs/components/scroll-area.md): A scrolling region with Koala's own scrollbar: an ink pill that overlays the content, shows while you are over it, fades rather than blinks, and looks the same on every OS and theme. The scrolling itself stays native.
- [Select](https://www.koalaui.com/docs/components/select.md): A dropdown for picking one value from a list. Built on Radix Select for keyboard navigation, type-ahead and a11y, with interruptible enter and exit. Its sibling SelectSearch adds a search field.
- [Sheet](https://www.koalaui.com/docs/components/sheet.md): A panel that stays open over a full-bleed canvas like a map: a floating card on a wide container, a bottom sheet with three detents on a narrow one. Unlike Drawer, it never blocks the page.
- [Sidebar](https://www.koalaui.com/docs/components/sidebar.md): The application navigation rail. Stack the parts you need: a workspace switcher up top, the primary pages first, labeled sections and favorites below, and a profile switcher pinned to the bottom.
- [Signature](https://www.koalaui.com/docs/components/signature.md): A handwritten signature that writes itself, stroke by stroke, at the pace a hand signs. Close a letter, a testimonial or a hero with it, or sign a Signature Pad and play the hand back.
- [Signature Pad](https://www.koalaui.com/docs/components/signature-pad.md): A page to sign on with a mouse, a finger or a stylus. It keeps each pen stroke as a smooth SVG path, in writing order, so a Signature can play the hand back and a form can submit it.
- [Skeleton](https://www.koalaui.com/docs/components/skeleton.md): A loading placeholder that mirrors the shape of the content it stands in for. Single-element like Badge; the fill is a semantic token, so it re-themes everywhere, and the optional shimmer rides the shared motion tokens.
- [Slider](https://www.koalaui.com/docs/components/slider.md): Pick a value or a range by dragging along a track. Built on Radix Slider: thumbs auto-render from the value array, with an optional live bubble and full keyboard support. SliderInput pairs a rail with a number.
- [Spinner](https://www.koalaui.com/docs/components/spinner.md): The one loading glyph in the system. It takes its size from whatever holds it and its color from the text around it, and it is announced once, never twice.
- [Stepper](https://www.koalaui.com/docs/components/stepper.md): A progress indicator for sequential flows: onboarding, checkout and multi-step dialogs. Each step derives its state from a single active value, and the connecting line fills as you advance.
- [Switch](https://www.koalaui.com/docs/components/switch.md): A toggle for an instant, self-applying boolean, built on Radix Switch. Use it for settings that take effect immediately (notifications, airplane mode); reach for a Checkbox when the choice is submitted with a form.
- [Table of Contents](https://www.koalaui.com/docs/components/table-of-contents.md): The on-this-page nav beside a long document. It marks the section being read as you scroll, with a bar that slides along a hairline track, and it needs nothing but the links themselves.
- [Tabs](https://www.koalaui.com/docs/components/tabs.md): Switch between related panels. Built on Radix Tabs for behavior and a11y, styled with one tv slots recipe. The active state is a single indicator measured in JS and slid with transform.
- [Textarea](https://www.koalaui.com/docs/components/textarea.md): A multi-line text field built from slots and Context: pairs with a label and hint, grows to fit its content, and carries an optional character counter in its footer. Each part is a named export.
- [Toast](https://www.koalaui.com/docs/components/toast.md): Transient status messages anchored to a corner. Toasts stack with a compressed fan when several are queued, hover to expand, follow a promise from loading to its result, and update in place.
- [Toggle](https://www.koalaui.com/docs/components/toggle.md): One control that stays pressed: bookmark, pin, mute, unread only. The single-item sibling of Toggle Group, sharing its paint and its heights, with a pressed glyph that fills in instead of blinking.
- [Toggle Group](https://www.koalaui.com/docs/components/toggle-group.md): A set of pressable pills that hold a selection, built on Radix ToggleGroup. Use single for a one-of-N choice or multiple for independent toggles. A chosen pill carries the brand outline.
- [Toolbar](https://www.koalaui.com/docs/components/toolbar.md): A keyboard-navigable band that groups icon controls, dropdown triggers, toggle sets and separators into one unit. Built on Radix Toolbar, so it ships roving tab focus and arrow-key movement.
- [Tooltip](https://www.koalaui.com/docs/components/tooltip.md): A small hint shown on hover or focus. Positioning, hover-intent and a11y come from Tippy.js in headless mode - Koala owns the bubble's markup, styled with our tokens. The one component built on a non-Radix primitive.
- [Tree](https://www.koalaui.com/docs/components/tree.md): A nesting tree view for file explorers, category browsers and any hierarchy. Built on Radix Collapsible, with single selection, full keyboard navigation and CSS guide rails that trace every level.
- [Video Player](https://www.koalaui.com/docs/components/video-player.md): A native way to play media: a real video element wrapped in a composable control surface. The scrubber and volume bar are Radix Sliders, and the controls auto-hide and stay legible over any frame.

## Application UI / Sections

- [Authentication](https://www.koalaui.com/app/sections/authentication.md): Complete sign-in and sign-up screens, ready to drop in. Seven layouts built from the LoginForm, SignUpForm and ProviderForm blocks: split pages, centered cards, magic links and Discord screens.
- [Dashboard](https://www.koalaui.com/app/sections/dashboard.md): Fifteen complete application screens on the docked app shell, ready to drop in. Eleven belong to one workspace, from the revenue overview and the forecast to finance, the people directory and the support team; four are verticals with navigation of their own: a fuel depot, a clinic's appointments, a camera wall and a legal code.
- [CRM](https://www.koalaui.com/app/sections/crm.md): A customer's record, ready to drop in. The person and the next actions, the account facts beside them, and tabs for everything that happened: spending KPIs behind a period switch, charts, orders, invoices, activity and notes.
- [Tasks](https://www.koalaui.com/app/sections/tasks.md): A project's work as a board, ready to drop in. Four columns of task cards with assignees, due dates and priorities, scoped by tabs, searched and sorted from one toolbar, and moved between columns by dragging.
- [Mail](https://www.koalaui.com/app/sections/mail.md): A shared support inbox, ready to drop in. The conversations, the open thread with a reply box, and the customer's card side by side in three panes, with every action wired: read state, status, pinning, archiving and replies.
- [Chat](https://www.koalaui.com/app/sections/chat.md): The team's messages, ready to drop in. The conversations, the open thread with a composer, and the person or group beside it in three panes, read two ways: as bubbles or as a thread, with photos, files, reactions and replies all wired.
- [Onboarding](https://www.koalaui.com/app/sections/onboarding.md): The screen a new workspace opens on, ready to drop in. A welcome, a bar that counts every step, and the setup steps grouped into sections that open one at a time, each with its own action.

## Ecommerce / Sections

- [Product List](https://www.koalaui.com/ecommerce/sections/product-list.md): The grids a store is browsed through: a simple four-up grid, a new-arrivals row with ratings and a quick add, and a full category page whose filters, sort and count are live. Every tile is the same card.
- [Product Overview](https://www.koalaui.com/ecommerce/sections/product-overview.md): The top of a product page: the photos and the buy box. A swipeable gallery beside live pickers and a details accordion, a photo grid that opens in a lightbox, or an editorial split with stock per size.
- [Shopping Cart](https://www.koalaui.com/ecommerce/sections/shopping-cart.md): The cart, as a page or as a slide-over. Both are live: change a quantity and the line total, subtotal, tax and free-shipping meter roll to the new figures; remove a line and it collapses out.
- [Checkout](https://www.koalaui.com/ecommerce/sections/checkout.md): Complete payment and checkout screens, ready to drop in. Two finished layouts: a SaaS billing page and an ecommerce one-page checkout, each pairing a form with the order summary that never disappears on mobile.

## Ecommerce / Pages

- [Storefront](https://www.koalaui.com/ecommerce/pages/storefront.md)
- [Category](https://www.koalaui.com/ecommerce/pages/category.md)
- [Product](https://www.koalaui.com/ecommerce/pages/product.md)
- [Shopping Cart](https://www.koalaui.com/ecommerce/pages/cart.md)