Overview
Installation
Install ferry-ui from npm, then add a stylesheet and the fonts.
| Requirement | Detail |
|---|---|
react and react-dom 19 | Components take ref as a regular prop. ferry-ui does not support React 18. |
| An ESM toolchain | Vite, Next.js or another modern bundler. The package is ESM only. |
tailwindcss 4.1 or later | Necessary only if your app compiles ferry-ui/theme.css. |
The package has one module for each component. Your bundle contains only the components that your app imports.
Radix UI, lucide-react, cmdk, sonner and the class helpers are dependencies of the package. Your package manager installs them with ferry-ui.
$ npm install ferry-uiUse the repository to try a version that is not on npm.
Build a tarball in the ferry-ui folder. The npm pack command builds the package first.
$ npm install $ npm pack
The command writes the file ferry-ui-0.1.0.tgz. Install this file in your app.
$ npm install ../ferry-ui/ferry-ui-0.1.0.tgzDo not install ferry-ui as a git dependency. The repository does not contain the dist/ folder, and npm does not build it for a git dependency. Clone the repository. Then build the tarball.
$ git clone https://github.com/Carter2307/ferry-ui.git $ cd ferry-ui && npm ci && npm pack $ cd ../my-app && npm install ../ferry-ui/ferry-ui-0.1.0.tgz
Install the ferry-ui folder itself. npm then makes a symlink to the folder.
$ npm install ../ferry-uiYour app reads the dist/ folder. Run npm run build in the ferry-ui folder after each change.
Make your bundler use one copy of React. This example is for Vite.
import { defineConfig } from 'vite'
export default defineConfig({
resolve: { dedupe: ['react', 'react-dom'] },
})Import each component, hook and helper from 'ferry-ui'.
import { Button } from 'ferry-ui'Do not import from ferry-ui/dist. These paths are not part of the API.
ferry-ui has four stylesheet entry points.
| Entry point | Content | Use |
|---|---|---|
ferry-ui/theme.css | The tokens, the Tailwind v4 theme, the dark variant, the base styles and the utilities. | Your app uses Tailwind CSS v4. |
ferry-ui/styles.css | Compiled CSS: the Tailwind preflight, the tokens and each class of the components. | Your app does not use Tailwind. |
ferry-ui/fonts.css | The Inter and Source Code Pro fonts. | You want the default fonts. |
ferry-ui/tokens.css | The CSS variables only. | Another stack needs the tokens, for example emails or a marketing site. |
Import the theme in your main stylesheet, after Tailwind.
@import "tailwindcss";
@import "ferry-ui/fonts.css"; /* optional */
@import "ferry-ui/theme.css";The theme gives the files of ferry-ui to Tailwind as a source. You do not write an @source rule or a content list. Your code can use the same token classes, for example bg-surface-100 and text-foreground-light.
If your project folder is not a git repository, add a .gitignore file that lists your build output. Tailwind reads this file to find the folders that it must not scan.
Import the compiled stylesheet one time, at the root of the app. It includes the preflight reset of Tailwind.
import 'ferry-ui/styles.css'
import 'ferry-ui/fonts.css' // optionalStyle your own markup with plain CSS and the variables, for example var(--surface-100).
The tokens name two font families.
| Variable | Fonts |
|---|---|
--ferry-ui-font-sans | Inter, then the system fonts. |
--ferry-ui-font-mono | Source Code Pro, then the system monospace font. |
ferry-ui/fonts.css loads the two families as variable fonts. The fonts come from packages that ferry-ui installs. The browser sends no request to a font CDN.
To use the system fonts, do not import fonts.css. To use other fonts, load them in your app and override the two variables.
:root {
--ferry-ui-font-sans: "Geist", system-ui, sans-serif;
--ferry-ui-font-mono: "Geist Mono", ui-monospace, monospace;
}