# ferry-ui

> ferry-ui is a React 19 design system for product interfaces (dashboards, admin consoles, settings pages, data tables, developer tools): design tokens, accessible primitives on Radix UI, patterns and application-shell layout pieces, styled with Tailwind CSS v4.

Install the package with `npm install ferry-ui`. Import everything from the package root (`import { Button } from 'ferry-ui'`). Each link below is the Markdown version of a documentation page.

## Overview

- [Quick start](/docs/overview/quick-start.md): Install ferry-ui, add its styles and show your first component.
- [Installation](/docs/overview/installation.md): Install ferry-ui from npm, then add a stylesheet and the fonts.
- [Accessibility](/docs/overview/accessibility.md): What ferry-ui does for accessibility, and what your code must do.
- [Releases](/docs/overview/releases.md): The versions of ferry-ui and the content of each version.
- [About ferry-ui](/docs/overview/about.md): What ferry-ui is, who it is for, and the ideas behind its design.

## Handbook

- [Styling](/docs/handbook/styling.md): The rules to style a screen with token classes, props and the utility classes of ferry-ui.
- [Tokens](/docs/handbook/tokens.md): The colors, the radii, the shadows and the fonts of ferry-ui, as Tailwind classes and CSS variables.
- [Theming](/docs/handbook/theming.md): The light theme, the dark theme, a theme picker, and the colors and fonts of your product.
- [Composition](/docs/handbook/composition.md): How the components of ferry-ui go together with parts, asChild, slot props and state props.
- [Forms](/docs/handbook/forms.md): How to build a form with fields, a settings card, validation errors and a save bar.
- [Routing](/docs/handbook/routing.md): How the links of ferry-ui work with React Router, Next.js, TanStack Router or plain anchors.
- [Server Components](/docs/handbook/server-components.md): How to use ferry-ui in an app that has React Server Components.
- [TypeScript](/docs/handbook/typescript.md): The types that ferry-ui exports, and how to use them in your own components.
- [AI agents](/docs/handbook/ai-agents.md): The files and the links that give the rules of ferry-ui to an AI agent.

## Examples

- [Dashboard](/docs/examples/dashboard.md): The home page of a signed-in app, with facts, numbers, a grid of projects and a table of events.
- [List page](/docs/examples/list-page.md): A page that lists records in a table, with a search field, a status filter and row actions.
- [Detail page](/docs/examples/detail-page.md): The page of one record, with its status, its facts, its credentials and tabs for the other views.
- [Settings](/docs/examples/settings.md): A settings area with a side menu, one form, a save bar and a danger zone.

## Primitives

- [Alert Dialog](/docs/components/alert-dialog.md): A dialog that stops the user until they answer a question.
- [Avatar](/docs/components/avatar.md): A round picture for a person, a team or an organization, with a fallback.
- [Badge](/docs/components/badge.md): A small label for short static data, such as a plan, a version, a count or a tag.
- [Breadcrumb](/docs/components/breadcrumb.md): A row of links that shows the place of the page in a hierarchy.
- [Button](/docs/components/button.md): A control that starts an action.
- [Card](/docs/components/card.md): A panel with a border that groups the content and the actions of one topic.
- [Checkbox](/docs/components/checkbox.md): A control for an on/off choice that applies on submit.
- [Collapsible](/docs/components/collapsible.md): A region that one trigger shows and hides.
- [Command](/docs/components/command.md): A search field above a list that the user filters and moves through with the keyboard.
- [Dialog](/docs/components/dialog.md): A window on top of the page for one task or one form.
- [Dropdown Menu](/docs/components/dropdown-menu.md): A short list of actions or options that opens from a trigger.
- [Input](/docs/components/input.md): A field for one line of text.
- [Label](/docs/components/label.md): The visible name of one form control.
- [Popover](/docs/components/popover.md): A small panel that opens next to its trigger and holds a form or a picker.
- [Radio Group](/docs/components/radio-group.md): A group of options where the user selects one value.
- [Scroll Area](/docs/components/scroll-area.md): A container that scrolls its content and shows a thin scrollbar in the colors of the theme.
- [Select](/docs/components/select.md): A control that opens a list of options and takes one value.
- [Separator](/docs/components/separator.md): A thin line that divides two groups of content.
- [Sheet](/docs/components/sheet.md): A panel that slides in from an edge of the screen and keeps the page in view.
- [Skeleton](/docs/components/skeleton.md): A placeholder block that takes the place of content while the content loads.
- [Switch](/docs/components/switch.md): An on/off control for a setting that applies immediately.
- [Table](/docs/components/table.md): A table for records that people compare by column, such as members, invoices or orders.
- [Tabs](/docs/components/tabs.md): A set of panels in one view, with one panel in view at a time.
- [Textarea](/docs/components/textarea.md): A field for text on more than one line.
- [Toast](/docs/components/toast.md): A short message that shows above the page after an action.
- [Toggle](/docs/components/toggle.md): A button with two states that stays pressed until the next click.
- [Toggle Group](/docs/components/toggle-group.md): A row of toggles that share one value.
- [Tooltip](/docs/components/tooltip.md): A short text that shows when the pointer or the focus is on an element.

## Patterns

- [Callout](/docs/components/callout.md): A tinted message that stays on the page, next to the content that it is about.
- [Code Block](/docs/components/code-block.md): A code sample or a command in the monospace font, with a copy button.
- [Confirm Dialog](/docs/components/confirm-dialog.md): A dialog that asks the user to confirm an action before the action runs.
- [Copy](/docs/components/copy.md): A button, a field and a secret field that copy a value to the clipboard.
- [Description List](/docs/components/description-list.md): A list of read-only facts about one record, as labels and values.
- [Empty State](/docs/components/empty-state.md): A placeholder for an area that has no content to show, and a box for a load that failed.
- [Field](/docs/components/field.md): A form field with a label above the control and a hint or an error below it.
- [Form Card](/docs/components/form-card.md): A card for a settings form, with one row for each setting and a footer that saves.
- [Icon Box](/docs/components/icon-box.md): A square with a border that holds one icon and shows the kind of an item.
- [Info Tile](/docs/components/info-tile.md): A tile with an icon, a label and a value for one fact about a record.
- [Kbd](/docs/components/kbd.md): A small keycap that shows a key of the keyboard.
- [Key Value Editor](/docs/components/key-value-editor.md): A list of key and value pairs that the user can edit, with validation, masked values and import.
- [List Toolbar](/docs/components/list-toolbar.md): The row of search, filters and actions above a list, a table or a grid.
- [Metric Card](/docs/components/metric-card.md): A card for one KPI number, with a trend, a usage bar or a chart.
- [Mono Label](/docs/components/mono-label.md): A small uppercase caption in the monospace font.
- [Page](/docs/components/page.md): The column, the title block and the sections that give each page the same structure.
- [Radio Card Group](/docs/components/radio-card-group.md): A group of cards where the user selects one option, each with a title and a description.
- [Resource Card](/docs/components/resource-card.md): A card that opens one named thing, and the grid that holds the cards.
- [Save Bar](/docs/components/save-bar.md): A footer for an editor or a long form, with the save status, Cancel and Save.
- [Split Button](/docs/components/split-button.md): A main action button with a second button that opens a menu of alternatives.
- [Status](/docs/components/status.md): Three components that show the state of a record with a tone and a label.
- [Table States](/docs/components/table-states.md): The rows that show the loading, empty and error states of a table.

## Layout

- [App Shell](/docs/components/app-shell.md): The frame of an application, with a top bar, a side rail and one region that scrolls.
- [Command Menu](/docs/components/command-menu.md): A dialog with a search field that opens a page or runs a command.
- [Icon Rail](/docs/components/icon-rail.md): The side navigation of an application, with icons and labels that the user can hide.
- [Inner Menu](/docs/components/inner-menu.md): A side menu for the sections of one area, such as the settings of an app.
- [Mobile Nav](/docs/components/mobile-nav.md): The navigation drawer of an application on a phone.
- [Resource Switcher](/docs/components/resource-switcher.md): A button that opens a list of projects, workspaces or teams with a search field.
- [Theme Menu](/docs/components/theme-menu.md): A round button that opens a menu with the light, dark and system themes.
- [Top Bar](/docs/components/top-bar.md): The header of an application, with a logo, a trail of segments and a group of actions.

## Utilities

- [cn](/docs/utilities/cn.md): A function that joins class names and removes the Tailwind classes that conflict.
- [getErrorMessage](/docs/utilities/get-error-message.md): A function that returns a readable message for each value that code can throw.
- [LinkProvider](/docs/utilities/link-provider.md): A provider that sends each link of ferry-ui through the link component of your router.
- [ThemeProvider](/docs/utilities/theme-provider.md): A provider that applies the light theme or the dark theme and keeps the preference of the user.
- [useCommandShortcut](/docs/utilities/use-command-shortcut.md): A hook that runs a function when the user presses the command key or the control key with a letter.
- [useCopy](/docs/utilities/use-copy.md): A hook that copies text to the clipboard and holds the state of a copy button.
- [usePlatform](/docs/utilities/use-platform.md): Two hooks and two constants that tell if the user has an Apple platform, for keyboard hints.