Quick start

Install the library#

ferry-ui is one package. It needs React 19.

$ npm install ferry-ui

Your bundle contains only the components that your app imports.

Add the styles#

Your app uses Tailwind CSS v4? Import the theme of ferry-ui after Tailwind.

@import "tailwindcss";
@import "ferry-ui/fonts.css"; /* optional: Inter and Source Code Pro */
@import "ferry-ui/theme.css";

Your app does not use Tailwind? Import the compiled stylesheet at the root of the app.

import 'ferry-ui/styles.css'
import 'ferry-ui/fonts.css' // optional

Mount the providers#

Mount the providers one time, at the root of the app.

import type { ReactNode } from 'react'
import { ThemeProvider, Toaster, TooltipProvider } from 'ferry-ui'

export function Providers({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider defaultTheme="system">
      <TooltipProvider>
        {children}
        <Toaster />
      </TooltipProvider>
    </ThemeProvider>
  )
}

Show a component#

Import each component from the package root. This example shows an empty list with one action.

import { Button, EmptyState, toast } from 'ferry-ui'
import { FolderKanban, Plus } from 'lucide-react'

export default function NoProjects() {
  return (
    <EmptyState
      icon={<FolderKanban />}
      title="No projects yet"
      description="Projects group your invoices, members and API keys."
      actions={
        <Button variant="primary" icon={<Plus />} onClick={() => toast.success('Project created')}>
          New project
        </Button>
      }
    />
  )
}

Use ferry-ui with an AI assistant#

Each page has a View as Markdown link. Give this link to your assistant.

The file llms.txt lists all the pages. The repository also has an AGENTS.md file with the rules, the tokens and the full catalog.

Next steps#

• Read Styling to learn the tokens and the rules for className.
• Read Theming to give ferry-ui the colors of your product.
• Open a component page, for example Button.