@fish-admin/react

FishAdmin UI — the React component library behind FishAdmin. It ships 83 components built on Radix UI, Tailwind CSS v4 and React 19, plus the design tokens and utilities the admin template uses.

The package is ESM-only and has no router, store or i18n runtime dependency.

Install

pnpm add @fish-admin/react

React and React DOM 19 are peer dependencies:

pnpm add react@^19 react-dom@^19

Styles

Import the compiled stylesheet once, usually next to your app entry:

import '@fish-admin/react/styles.css'

styles.css contains the compiled design tokens, the bg-brand / shadow-soft style utilities and a minimal base layer. It deliberately does not include Tailwind's preflight, so it cannot reset an existing application's CSS. If your app has no reset of its own, opt in explicitly:

import '@fish-admin/react/preflight.css'
import '@fish-admin/react/styles.css'

Design tokens

The colour, radius and motion values are generated from @fish-admin/tokens, inlined into styles.css; you do not need to install that package to use the components. styles.css also carries the prefers-contrast: more overrides and the forced-colors rules that keep focus, disabled and selected states visible.

Seven overlays — Dialog, Sheet, Drawer, DropdownMenu, Popover, Tooltip and Accordion — animate with --motion-duration-fast/base/slow and --motion-ease-standard/emphasized/exit, and disable their animation under prefers-reduced-motion: reduce. Override those custom properties to retime them. To read the full contract, build a theme editor or export CSS, install @fish-admin/tokens separately; its editor entry point is browser-safe.

Tailwind CSS v4

If your app runs Tailwind 4 and you want to compose new classes with the package's tokens, point Tailwind at the published artifacts:

@import 'tailwindcss';
@source 'node_modules/@fish-admin/react/dist';

Usage

import { Button, UIProvider } from '@fish-admin/react'

export function App() {
  return (
    <UIProvider locale="zh-CN" theme="dark">
      <Button>保存</Button>
    </UIProvider>
  )
}

UIProvider supplies the locale used by date, number and CSV formatting, the resolved theme used by portalled overlays, and the UI copy. Props:

| Prop | Type | Default | | ---------- | ------------------------------- | --------- | | locale | 'en' \| 'zh-CN' | 'en' | | theme | 'light' \| 'dark' \| 'system' | 'light' | | messages | Record<string, string> | {} |

messages overrides individual UI strings on top of the built-in locale; use {{name}} placeholders for interpolation. Without a provider the components fall back to English and the light theme, so a provider is optional.

Maturity

All 83 components are stable. A component counts as stable only while it holds this evidence: a documentation page in both locales, a live demo, a behavioural test, axe coverage of its documented route and light and dark visual baselines. The docs site renders the matrix at /guide/maturity.

pnpm --filter @fish-admin/react test
pnpm --filter @fish-admin/react test:coverage
pnpm check:maturity

The suite is 93 files and 303 tests. test:coverage enforces floors of 77% statements, 68% branches, 78% functions and 79% lines. pnpm check:maturity re-derives the evidence from disk and fails when a stable component loses any piece of it, so keeping the label means keeping the test, the axe coverage and both baselines; without that evidence a component cannot stay stable and would have to be marked beta with a written reason.

Entry points

• @fish-admin/react — all components, hooks, utilities and UIProvider.
• @fish-admin/react/styles.css, @fish-admin/react/preflight.css — styles.
• @fish-admin/react/internal/* — data-table, page-header, date, tree and CSV helpers. These exist for the FishAdmin template and are not promised to stay stable across minor releases.