@classytic/fluid

React 19 component library on top of shadcn/ui + Base UI. Built for Next.js 16 App Router; most entry points are framework-agnostic. ESM-only, server/client split, RSC-friendly, no design-system lock-in (you keep your own shadcn primitives at @/components/ui/*).

The package exposes 106 JavaScript subpaths plus 4 stylesheets: 31 barrels (@classytic/fluid, /forms, /dashboard/client, …) and a granular path for every public form component, client component, and hook (@classytic/fluid/forms/form-input, /client/card-wrapper, /hooks/use-debounce). Reach for the granular paths when per-route compile time matters — see Entry points.

Install

npm install @classytic/fluid

1. Install core peer deps

npm install react react-dom lucide-react class-variance-authority clsx tailwind-merge

2. Install shadcn primitives fluid wraps (40 components, one command)

npx shadcn@latest add accordion alert alert-dialog avatar badge breadcrumb button calendar card checkbox collapsible combobox command context-menu dialog drawer dropdown-menu empty field hover-card input input-group input-otp item kbd navigation-menu pagination popover progress radio-group resizable scroll-area select separator sheet sidebar skeleton switch table tabs textarea tooltip

If you only need a subset, see the peer-dep table and add only the shadcn components your imports need.

3. Import styles

// app/layout.tsx
import "@classytic/fluid/styles.css"
import "@classytic/fluid/document/print.css"  // if you use the document subsystem

4. Transpile (Next.js only)

// next.config.ts
export default { transpilePackages: ["@classytic/fluid"] }

5. (Optional) Wrap with FluidProvider for i18n label overrides:

import { FluidProvider } from "@classytic/fluid/client/core"
export default function RootLayout({ children }) {
  return <FluidProvider>{children}</FluidProvider>
}

Tailwind v4 required. styles.css uses @source and @theme inline — Tailwind v3 throws.

Next.js is optional. dashboard/client, search, and layouts import next/navigation or next/link; client/gallery and client/thumbnail import next/image. Everything else is framework-neutral — see the peer-dep table.

Quick example

import { useForm } from "react-hook-form"
import { FormInput, FormTextarea, FormSection } from "@classytic/fluid/forms"
import { ClientSubmitButton } from "@classytic/fluid/client/core"

function ContactForm() {
  const { control, handleSubmit } = useForm()
  return (
    <form onSubmit={handleSubmit(console.log)} className="space-y-4">
      <FormSection title="Contact">
        <FormInput control={control} name="email" label="Email" required />
        <FormTextarea control={control} name="message" label="Message" rows={4} />
      </FormSection>
      <ClientSubmitButton>Send</ClientSubmitButton>
    </form>
  )
}

Form submission — four styles, one contract

FormSurface (from @classytic/fluid/forms) is the <form> element the overlays render. It decides when to render a form, when to prevent the default, and whether native validation runs — so every overlay behaves the same.

React 19 Server Action. Pass action; the submit is not prevented, FormData is collected natively, the form works before hydration, and the submit button derives its pending state from useFormStatus — no submitLoading prop:

<FormDialog open={open} onOpenChange={setOpen} action={createCustomer} title="New customer">
  <FormInput name="email" label="Email" required />
</FormDialog>

react-hook-form / formkit. The default. noValidate is set for you, so schema rules and focusFirstError run instead of native bubbles:

<FormDialog open={open} onOpenChange={setOpen} onSubmit={form.handleSubmit(save)} title="Edit">…</FormDialog>

@classytic/formkit is react-hook-form under the hood, so SchemaForm/SchemaFormDialog/SchemaFormSheet are always this mode — don't pass action to a formkit form, the two submission models are mutually exclusive. Use applyServerErrors(form, fieldErrors) to fold server-returned errors back into the form.

Whole-form validation. Pass any Standard Schema validator directly; input and parsed submit types are inferred. This works in SchemaForm, dialog, sheet, and drawer variants:

const validationSchema = z.object({ age: z.string().transform(Number) })
<SchemaForm
  schema={ageFormSchema}
  validationSchema={validationSchema}
  onSubmit={(values, form) => {
    values.age.toFixed() // parsed number
    form.watch("age")   // raw string
  }}
/>

A supplied resolver takes precedence over validationSchema. Without either, schema field rules enforce validation through the registered controls.

Where to import the builders from. @classytic/fluid/formkit is "use client" — it carries SchemaForm and the shadcn adapter — so importing field/section from it makes your schema a client module too. A schema is plain data; keep it on the server-safe subpath and let the client boundary live with the renderer:

// schedule-schema.ts — no "use client"; importable from an RSC, a server action or a node test
import { defineSchema, field, section } from "@classytic/fluid/formkit/builders"
export const schema = defineSchema({ sections: [section("id", "Details", [field.text("name", "Name")])] })

// form.tsx — the boundary belongs here
"use client"
import { SchemaForm } from "@classytic/fluid/formkit"
import { schema } from "./schedule-schema"

@classytic/formkit/server is equally server-safe and is the better choice when you author with field.for<T>() or an explicit <TFieldValues> generic; ./formkit/builders exists for Fluid's de-generic field/section, which let mixed-name, string-path field arrays unify under strict TS.

External form (sheets). FormSheet and EntitySheet bind to a form you render, so a Server Action works there natively. The footer sits outside that form, so useFormStatus can't reach it — pass submitLoading from useActionState:

const [state, formAction, isPending] = useActionState(createCustomer, null)

<EntitySheet open={open} onOpenChange={setOpen} mode="create" entityName="Customer"
  formId="customer-form" submitLoading={isPending}>
  <form id="customer-form" action={formAction}>
    <FormInput name="email" label="Email" required />
  </form>
</EntitySheet>

Imperative. No form — give submit.onClick a handler and the button becomes a plain button.

Entry points

| Entry | Server-safe | Purpose | |---|:-:|---| | @classytic/fluid | ✅ | Layout, display, states, skeletons, utils | | @classytic/fluid/client/hooks | — | Hooks + storage (no next/navigation) | | @classytic/fluid/client/core | — | Dialogs, cards, pills, tabs, animations, providers | | @classytic/fluid/client/table | — | DataTable + toolbar | | @classytic/fluid/client/table-virtualized | — | Opt-in row-windowing for DataTable (large datasets) | | @classytic/fluid/client/theme | — | ModeToggle | | @classytic/fluid/client/error | — | ErrorBoundary, AsyncBoundary | | @classytic/fluid/client/calendar | — | EventCalendar | | @classytic/fluid/client/color-picker | — | Composable HSL color picker | | @classytic/fluid/client/gallery | — | Image gallery + lightbox | | @classytic/fluid/client/spreadsheet | — | Editable spreadsheet table | | @classytic/fluid/forms | — | Form components (react-hook-form integration) | | @classytic/fluid/floating-label | — | Material-style floating-label inputs | | @classytic/fluid/dashboard | ✅ | Nav utils, breadcrumbs, types, DashboardContent, PageShell, AppsGrid | | @classytic/fluid/dashboard/client | — | Sidebar presets, useDashboardBreadcrumbs, HeaderActions | | @classytic/fluid/dashboard/resource-dashboard | — | ResourceDashboard | | @classytic/fluid/document | ✅ | Document/print primitives, pagination utils | | @classytic/fluid/document/client | — | DocumentMultipage, DocumentPaginator | | @classytic/fluid/numpad | — | <Numpad> + headless useNumpad | | @classytic/fluid/search | — | Composable search system, URL-synced | | @classytic/fluid/command | — | Command palette + keyboard shortcuts | | @classytic/fluid/layouts | — | NavigationBar, ResponsiveSplitLayout | | @classytic/fluid/seo | ✅ | JSON-LD wrappers + Next 16 Metadata helpers |

All entries resolve @/components/ui/* from your project's shadcn setup at build time.

Server / Client split — donut pattern

// app/dashboard/layout.tsx — Server Component (no "use client")
import { DashboardContent } from "@classytic/fluid/dashboard"
import { InsetSidebar } from "@classytic/fluid/dashboard/client"
import { SidebarProvider, SidebarInset } from "@/components/ui/sidebar"

export default function Layout({ children }) {
  return (
    <SidebarProvider>
      <InsetSidebar brand={brand} navigation={nav} />
      <SidebarInset className="min-w-0">
        <DashboardContent>{children}</DashboardContent>
      </SidebarInset>
    </SidebarProvider>
  )
}

{children} passes through the client boundary as a server-rendered hole — page content is prerendered. Same pattern applies to @classytic/fluid/document and @classytic/fluid/document/client.

Composing a preset yourself? Add the skip link. DashboardLayout renders <SkipLink /> first in DOM order and puts MAIN_CONTENT_ID on its <main>, so bypass-blocks (WCAG 2.4.1) is handled for you. Assemble the shell by hand — as above — and you own that. Without it, a keyboard user tabs through every nav item before reaching page content on every navigation:

import { MAIN_CONTENT_ID, SkipLink } from "@classytic/fluid/skip-link"

<SidebarProvider>
  <SkipLink />                {/* first in DOM order, or it skips nothing */}
  <InsetSidebar brand={brand} navigation={nav} />
  <SidebarInset className="min-w-0">
    <DashboardContent as="main" id={MAIN_CONTENT_ID}>{children}</DashboardContent>
  </SidebarInset>
</SidebarProvider>

CopilotSidebar and TopbarRail are self-contained shells and render their own — don't add a second one there.

Peer dependencies by entry point

Core peer deps (react, react-dom, lucide-react, class-variance-authority, clsx, tailwind-merge) are always required. Add the rest only when you import the corresponding entry:

| Entry | Additional peer deps | |---|---| | dashboard/client, search, gallery | next | | client/table | @tanstack/react-table | | client/table-virtualized | @tanstack/react-virtual (opt-in row-windowing for DataTable — importing client/table alone never pulls this in) | | client/spreadsheet | @tanstack/react-virtual | | client/theme | next-themes | | client/error | react-error-boundary | | client/calendar, forms | date-fns | | forms | react-hook-form |

Required Button size extensions

Fluid uses three icon-button sizes that aren't in stock shadcn: icon-xs, icon-sm, icon-lg. The latest shadcn registry button (Base UI variant) ships them, but if you scaffolded from older shadcn or hand-rolled @/components/ui/button.tsx, add them to the size cva variant:

size: {
  // ...existing default | sm | lg | icon
  "icon-xs": "size-6 rounded-[min(var(--radius-md),10px)] [&_svg:not([class*='size-'])]:size-3",
  "icon-sm": "size-7 rounded-[min(var(--radius-md),12px)]",
  "icon-lg": "size-9",
}

Used by: DrawerWrapper, FormFieldArray, FormPasswordInput, FormNumberInput, FloatingNumberInput, Search.Input, FileUploadInput.

Framework support

| Framework | Works | Doesn't | |---|---|---| | Next.js 15/16 | Everything | — | | Vite / Remix / plain React | All entries except those that import next/link / next/navigation | dashboard/client, search, layouts, gallery | | React Server Components | @classytic/fluid, dashboard, document, seo | Everything "use client" |

Docs

• Dashboard — sidebar presets, donut pattern, PageShell, RSC HeaderSection recipe, dynamic badges, define* builders
• DataTable / ResourceDashboard — pagination shapes, result overload, styling escape hatches, Suspense recipe
• Document subsystem — single-page, multi-page, paginator, POS receipt recipe
• Register-style primitives — useBarcodeScan, useWakeLock, <Numpad>, <HotkeyHelpDialog>, <AppsGrid>
• Components & hooks index — full cheat-sheet of every export

Customization

Four escape hatches — fluid wraps Base UI but never locks you out:

1. Pass your own labeled trigger. Trigger slots accept an element, which Base UI merges its trigger props into:

   <ActionDropdown trigger={<Button aria-label="Row actions"><MoreVertical /></Button>} ... />

2. Every Base UI root prop passes through, and is typed. All three overlays — DialogWrapper, SheetWrapper, DrawerWrapper — extend ComponentProps<typeof Dialog> / <typeof Sheet> / <typeof Drawer> rather than re-declaring a subset, so defaultOpen, onOpenChangeComplete, disablePointerDismissal, actionsRef — plus Drawer's full snap-point surface (snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — and anything Base UI adds later are available to TypeScript consumers — not just accepted at runtime:

   <DialogWrapper defaultOpen disablePointerDismissal onOpenChangeComplete={track}>…</DialogWrapper>

3. Reach individual parts with *Props. contentProps, headerProps, footerProps, titleProps, descriptionProps, triggerProps spread onto the matching element — that's where initialFocus, finalFocus, render, data-* and ARIA go. Styling still goes through the *ClassName props, which win over *Props so a size preset can't be broken by accident. ref lands on the popup.

   <SheetWrapper ref={popupRef} contentProps={{ initialFocus: searchRef }} … />

4. Drop to the Base UI primitive when you need full control — every wrapper documents its underlying primitive in JSDoc.

i18n labels (Save / Cancel / Loading... / kit-internal aria) flow from <FluidProvider labels={...}> so non-English a11y trees come out correctly without per-component overrides. Consumer-controlled content (titles, descriptions, empty messages) flows through component props with English defaults — FluidProvider is fully optional.

RTL

Set dir="rtl" (and lang) on <html>; fluid flips with it. Three rules make that work:

• Logical classes only. Fluid uses ms-/me-/ps-/pe-/start-/end-/text-start/text-end/rounded-s*/rounded-e*, never ml-/mr-/pl-/pr-/left-/right-. Direction-bearing icons (the table's scroll chevrons, the picker's back arrow) carry rtl:rotate-180, and the table's scroll buttons work in inline-start/end terms. Follow the same rule in host code.

• dir passthrough for LTR content. An email, code, URL or JSON field inside an RTL page should read left-to-right while its label and layout stay RTL: <FormInput dir="ltr" … /> (also FormTextarea, PasswordInput). In a formkit schema, set dir: "ltr" on the field; the adapter forwards field props.

• Every kit string goes through FluidLabels. Placeholders (selectPlaceholder, multiSelectPlaceholder, searchPlaceholder, dateRangePlaceholder), search chrome (filters, openFilters, reset, apply, clearFilters, removeFilter, yes/no), picker hints, the empty table cell (emptyCell) and date-range trigger text (formatDate, dateRange) all have English defaults you replace once:

  <FluidProvider labels={{ selectPlaceholder: "اختر", filters: "عوامل التصفية", formatDate: (d) => d.toLocaleDateString("ar-SA") }}>

  A prop on the component (placeholder, title, fallback, locale on DateRangeFilter / CivilDateRangeFilter) still wins for that one instance.

Host-owned shadcn components. The shadcn base-nova sidebar.tsx and sheet.tsx keep physical left-0/right-0 (and side-based border-l/border-r) even after shadcn migrate rtl. Every fluid dashboard host hits this: patch them to start-0/end-0 and border-s/border-e in your components/ui/, or the sidebar and sheets open on the wrong edge in RTL.

Responsive frame stories

Compose container-sized image sequences with granular scroll hooks, deferred loading, paint-ready posters and independently authored mobile layouts. See the frame-story guide for APIs and performance budgets; editable aperture and product choreography recipes live in examples/fluid. npm run check:scroll-chunks verifies their core imports stay isolated from optional integrations in both built JavaScript and declarations.

Motion and material

All of this ships in styles.css, so importing fluid's stylesheet is enough. Nothing here needs a JS import.

Motion tokens. Theme tokens, so they are also Tailwind utilities.

| Token | Utility | Use for | |---|---|---| | --ease-fluid-out | ease-fluid-out | Entering and exiting | | --ease-fluid-in-out | ease-fluid-in-out | Moving or morphing on screen | | --ease-fluid-drawer | ease-fluid-drawer | Sheets and drawers | | --transition-duration-fluid-press (160ms) | duration-fluid-press | Press feedback | | --transition-duration-fluid-pop (180ms) | duration-fluid-pop | Tooltips, small popovers | | --transition-duration-fluid-menu (220ms) | duration-fluid-menu | Dropdowns, selects | | --transition-duration-fluid-overlay (320ms) | duration-fluid-overlay | Modals, drawers |

The CSS built-in curves barely move in the first frames, which is where the eye is, so UI reads as hesitant at a duration where these feel instant. There is deliberately no ease-in. To apply the curves to bare ease-out / ease-in-out across your own markup too, opt in once:

@theme inline {
  --ease-out: var(--ease-fluid-out);
  --ease-in-out: var(--ease-fluid-in-out);
}

pressable adds scale(0.97) on :active and owns the colour transition, so it can be an element's one transition. Opt-in by class; stops moving under prefers-reduced-motion.

<button className="pressable">Save</button>

translucent is floating chrome that content scrolls under. It goes solid under prefers-reduced-transparency, solid with a real border under prefers-contrast: more, and solid where backdrop-filter is unsupported. Retune with two variables:

<header className="translucent [--fluid-translucent-tint:var(--card)] [--fluid-translucent-opacity:92%]" />

ScrollReveal (@classytic/fluid/client/scroll-reveal) is a one-shot clip-path wipe for marketing surfaces. It fires once and never re-hides, leaves an element already on screen alone, renders revealed without JavaScript, and clips nothing under reduced motion. Keep its rootMargin inset on the bottom only: a uniform negative margin trims the top as well, and elements that come to rest in that band never reveal.

<ScrollReveal from="bottom" delay={60}>…</ScrollReveal>

Layout primitives are also available as granular subpaths, @classytic/fluid/layout/container and @classytic/fluid/layout/section, so a page that wants a <Section> does not import the root barrel to get one.

Dev

npm run build                 # tsdown — 31 build entries, unbundled to ~570 dist files
npm run typecheck             # tsc --noEmit, against the ambient shadcn contract
npm run typecheck:conformance # ...and against the REAL shadcn components in examples/fluid
npm run lint                  # biome (workspace config at the repo root)
npm test                      # vitest
npm run check:exports         # package.json exports vs entrypoints.mjs

entrypoints.mjs is the single source of truth for the public surface — tsdown.config.ts and package.json's exports are both generated from it. Add a subpath there and run npm run sync:exports; check:exports fails the build on drift.

Requirements

React 19+, Next.js 15+, Tailwind v4, shadcn/ui at @/components/ui/*.

License

MIT

Trademark

The code is MIT-licensed. "Classytic", "arc", and the logos are trademarks of Classytic LLC and are not licensed under MIT — see TRADEMARK.md. Forks must be renamed; the license covers the code, not the brand.