# oks-ui — full context
> oks-ui is a strict-TypeScript React component library with a CSS-variable
> design system. Zero runtime dependencies beyond React, no theme provider, no
> configuration, accessible by default. MIT licensed and free.
>
> Homepage: https://www.oks-ui.com
> Package: https://www.npmjs.com/package/oks-ui
> License: MIT
## What it is
oks-ui gives you ~55 ready-made React components (buttons, modals, drawers,
forms, tables, charts, toasts, a command palette, a Kanban board, a block
editor, and more) with a consistent design system driven entirely by CSS custom
properties. Every color, space, radius, and shadow is an `--oks-*` variable, so
theming needs no build step, no config object, and no React context.
Design goals:
- **Strict TypeScript.** Built with `noUncheckedIndexedAccess`,
`exactOptionalPropertyTypes`, and the full strict suite. Props are stable and
intentional.
- **Zero runtime dependencies.** Nothing ships to your bundle except the
components themselves; the only peers are `react` and `react-dom`.
- **CSS-variable tokens.** Theme by overriding `--oks-*` properties from your own
CSS. Semantic roles (`primary`, `secondary`, `success`, `warning`, `danger`,
…) are aliases you can point at any palette.
- **Accessible by default.** Keyboard navigation, `:focus-visible` rings, ARIA
roles, and `prefers-reduced-motion` support are built into every component.
- **Opt-in utilities.** A prefixed `.oks-*` utility layer is available as a
separate CSS import for rapid prototyping alongside components.
## Install and use
```bash
npm install oks-ui
# or: pnpm add oks-ui / yarn add oks-ui
```
```ts
// Import the styles once, in your app entry or root layout:
import "oks-ui/styles.css";
```
```tsx
import { Button } from "oks-ui";
export function Example() {
return ;
}
```
No provider wrapper and no configuration are required. Components are named
exports from the package root: `import { Button, Modal, Table, Chart } from "oks-ui"`.
Per-component subpaths are also available if you only need one component and
its CSS: `import { Button } from "oks-ui/button"; import "oks-ui/button.css";`.
Style entry points:
- `oks-ui/styles.css` — tokens + utilities + component styles (recommended).
- `oks-ui/tokens.css` — just the `--oks-*` custom properties.
- `oks-ui/utilities.css` — just the prefixed `.oks-*` utility classes.
- `oks-ui/motion` — optional motion utilities.
Per-component entry points (oks-ui 1.2+): import just what you use, each with
its own stylesheet — `import { Button } from "oks-ui/button"` plus
`import "oks-ui/button.css"`. Every component has one (`oks-ui/table`,
`oks-ui/text-editor`, …); the `oks-ui` barrel keeps working.
Requires React 18 or newer. Works with the Next.js App Router (mark files that
render oks-ui components with `"use client"`; components carry no client
markers of their own).
## Theming
```css
:root {
/* Override any token */
--oks-color-primary-500: #7c3aed;
--oks-space-4: 18px;
/* Point a semantic role at a built-in palette */
--oks-color-secondary-500: var(--oks-palette-slate-500);
}
```
Dark mode is driven by a `data-theme="dark"` attribute on ``; token values
respond to it automatically. Built-in palettes include slate, gray, zinc,
neutral, stone, red, orange, amber, and more.
## Components (55)
Each component has an interactive props playground at
`https://www.oks-ui.com/components//`.
### Actions
- **Button** (`/components/button`): A pressable element with variants, colors, sizes, loading state, and ripple feedback.
- **ButtonGroup** (`/components/button-group`): Merges adjacent Buttons into a single control, sharing variant/color/size defaults.
### Feedback
- **Alert** (`/components/alert`): Contextual feedback message with icon, title, description, and dismiss.
- **Toast** (`/components/toast`): Provider-based toast notification system with a promise-aware API.
- **Loader** (`/components/loader`): Loading spinner for indeterminate progress, with 7 built-in variants.
- **Modal** (`/components/modal`): Dialog modal with focus trapping, keyboard dismissal, and safe stacking.
### Navigation
- **Tabs** (`/components/tabs`): Tabbed content navigation with a composable, roving-tabindex API.
- **Drawer** (`/components/drawer`): Slide-in panel from any edge of the viewport, built on the same overlay stack as Modal.
- **Dropdown** (`/components/dropdown`): Menu dropdown with triggers, sections, submenus, and opt-in virtualization.
- **SteppedForm** (`/components/stepped-form`): Multi-step form flow with progress tracking, built on FormFieldSet.
- **Nav** (`/components/nav`): Multi-level navigation tree with collapsible groups, active-route styling, an accordion mode, and a collapsed icon rail.
- **Breadcrumbs** (`/components/breadcrumbs`): Navigation trail with a chevron separator, collapse-to-ellipsis, and router-link polymorphism.
- **Pagination** (`/components/pagination`): Windowed page-number control for a list or table footer, with a "Showing X–Y of Z" summary.
- **SegmentedControl** (`/components/segmented-control`): Compact inline switch between a few mutually exclusive options, with an animated selection thumb.
- **CommandPalette** (`/components/command-palette`): The Cmd+K overlay: a search box over a fuzzy-filtered, grouped list of actions and destinations, with full keyboard navigation and a useCommandPalette hotkey hook.
### Data Display
- **Badge** (`/components/badge`): Notification badge with count, dot, and placement, plus a bump animation on change.
- **Avatar** (`/components/avatar`): User avatar with group support, status indicator, and image-load fallback.
- **Chip** (`/components/chip`): Compact tag or pill element, closable and selectable.
- **Tooltip** (`/components/tooltip`): Hover/focus tooltip with positioning logic and touch-aware delays.
- **Table** (`/components/table`): Config-driven data table with sorting, row selection, row expansion, a sticky header, and loading and empty states.
- **EmptyState** (`/components/empty-state`): Centered placeholder for an empty or no-match list, with an icon, title, description, and actions.
- **Progress** (`/components/progress`): Linear and circular progress indicators, determinate or indeterminate, with an optional value label.
- **Accordion** (`/components/accordion`): Collapsible sections with single-open or multiple modes, three visual variants, and animated open/close.
### Data Visualization
- **Line Chart** (`/components/chart-line`): Chart type="line" -- ChartLineOptions: curve style and stroke width.
- **Area Chart** (`/components/chart-area`): Chart type="area" -- a line chart with the area under it filled automatically.
- **Bar Chart** (`/components/chart-bar`): Chart type="bar" -- ChartBarOptions: stacked series and corner radius.
- **Column Chart** (`/components/chart-column`): Chart type="column" -- ChartColumnOptions: stacked series and corner radius.
- **Pie Chart** (`/components/chart-pie`): Chart type="pie" -- ChartPieStyleOptions: slice border. Single series, one value per slice.
- **Donut Chart** (`/components/chart-donut`): Chart type="donut" -- ChartPieStyleOptions: slice border and inner ratio.
- **Heatmap Chart** (`/components/chart-heatmap`): Chart type="heatmap" -- ChartHeatmapOptions: series as rows, categories as columns, one hue scaled by opacity across the value domain.
- **Chart States** (`/components/chart-states`): isLoading/error/empty -- real, separate props that each replace the chart entirely, shared across every chart type.
### Layout & Display
- **Divider** (`/components/divider`): Horizontal or vertical rule, with an optional inline label.
- **Backdrop** (`/components/backdrop`): Overlay backdrop for modals, drawers, and menus, with blur and stacking support.
- **PageTitle** (`/components/page-title`): Semantic page/section heading with an optional icon, subtitle, and tooltip.
- **Card** (`/components/card`): Bordered, rounded, elevated surface container, with header, body, and footer regions.
- **Stat** (`/components/stat`): KPI block with a label, value, trend delta pill, optional icon and sparkline, plus a responsive StatGroup.
- **Timeline** (`/components/timeline`): Vertical activity feed with dot or icon markers on a connector rail.
- **Calendar** (`/components/calendar`): Standalone month-grid view with single or range selection, min/max and per-day constraints, a renderDay slot for event markers, and full grid keyboard navigation.
- **SplitLayout** (`/components/split-layout`): Resizable multi-pane frame for email 3-pane, master-detail, and split editors, with keyboard-resizable dividers and collapsible panes.
- **Message** (`/components/message`): Chat message-thread primitives: a screen-reader-live MessageList and left/right-aligned Message bubbles with author, avatar, timestamp, delivery status, and continuation grouping.
- **Board** (`/components/board`): Data-driven Kanban board with dependency-free pointer, touch, and keyboard drag-and-drop, column card limits, and live-region announcements.
- **Skeleton** (`/components/skeleton`): Loading placeholder, as a shaped block or a wrapper that reveals its content once loaded.
### Forms
- **Text Field** (`/components/form-field-text`): FormFieldSet type="text" -- TextField, also covers number/url/search/color/email.
- **Textarea Field** (`/components/form-field-textarea`): FormFieldSet type="textarea" -- multi-line text with a length counter.
- **Select Field** (`/components/form-field-select`): FormFieldSet type="select" -- single/multi select with a custom popover or native mode.
- **Password Field** (`/components/form-field-password`): FormFieldSet type="password" -- reveal toggle and strong-password requirements.
- **OTP Field** (`/components/form-field-otp`): FormFieldSet type="otp" -- segmented or single-input one-time code entry.
- **Phone Field** (`/components/form-field-phone`): FormFieldSet type="phone" -- phone number with a country calling-code selector.
- **Range Field** (`/components/form-field-range`): FormFieldSet type="range" -- single or dual-thumb slider.
- **File Field** (`/components/form-field-file`): FormFieldSet type="file" -- inline or dropzone file upload with previews.
- **Switch Field** (`/components/form-field-switch`): FormFieldSet type="switch" -- toggle with optional on/off state text.
- **Radio Group Field** (`/components/form-field-radio`): FormFieldSet type="radio" -- single-select radio group.
- **Checkbox Group Field** (`/components/form-field-checkbox`): FormFieldSet type="checkbox" -- multi-select checkbox group.
- **Date Picker Field** (`/components/form-field-datepicker`): FormFieldSet type="datepicker" -- single date or range, with time and presets.
### Editors
- **TextEditor** (`/components/text-editor`): Block-based rich text editor (Notion-style) with 17 block types, slash-menu insertion, Markdown shortcuts, rich paste, and drag-and-drop reordering.
## Patterns
Full product screens assembled from oks-ui — a live preview and the complete
crawlable source, at `https://www.oks-ui.com/patterns//`.
- **Analytics dashboard** (`/patterns/analytics-dashboard`): A full fintech app screen — collapsible sidebar, header search, wallet cards, an earnings chart, savings goals, and a transactions table.
- **Sign-in screen** (`/patterns/sign-in`): A split-screen sign-in with a feature panel, Google SSO, and remember-me.
- **Settings panel** (`/patterns/settings-panel`): A real settings screen — top tabs, two-column sections, and a sortable, selectable billing history table.
- **Data table view** (`/patterns/data-table-view`): A full documents list screen — status Tabs, a filter toolbar, and a sortable, selectable Table with real recipient avatars.
- **Sign-up screen** (`/patterns/sign-up`): A dark canvas with a feature pitch, SSO row, and a real registration form.
- **Forgot password** (`/patterns/forgot-password`): A single email field beside an original customer-quote panel.
- **OTP verification** (`/patterns/otp-verify`): Four large circular code boxes with a live resend countdown.
- **Pricing table** (`/patterns/pricing-table`): Four plans with a live billing toggle and a per-feature check/x comparison list.
- **Product grid** (`/patterns/product-grid`): A responsive book grid with ratings, sale pricing, and a save-for-later action.
- **Checkout** (`/patterns/checkout`): A real two-step checkout — order review, discount codes, and a live payment-method switch.
- **Invoice detail** (`/patterns/invoice-detail`): A full-width invoice builder with a live Preview Drawer for the recipient-facing view.
- **Onboarding wizard** (`/patterns/onboarding-wizard`): A 3-column setup flow: a numbered step rail, the active step's form, and contextual tips.
- **Kanban board** (`/patterns/kanban-board`): A full project board — sidebar/header shell, filters, priority cards with subtask checklists, and drag-and-drop with WIP limits.
- **Team members table** (`/patterns/team-members`): A team-settings screen — checkbox-selectable Table, status/group Chips, and a real Pagination footer.
- **Chat thread** (`/patterns/chat`): A full omnichannel inbox — folder/channel rail, a message list, and a real MessageList conversation.
- **Notifications feed** (`/patterns/notifications-feed`): A tabbed notifications card — reactions, comments, attachments, image uploads, and a join request.
- **Calendar & schedule** (`/patterns/calendar-schedule`): A month calendar with event dots, past events, and a paginated upcoming-events list.
- **File manager** (`/patterns/file-manager`): A document-hub dashboard — an action toolbar, suggested folders, and a grid/list file view.
- **Command palette shell** (`/patterns/command-palette-shell`): A full sidebar/header app shell with a real ⌘K command palette wired to the header's search trigger.
- **Empty & error states** (`/patterns/empty-and-error-states`): A real list screen switching between its Loading, Empty, and Error states via Tabs.
## Recipes
Small, focused, copy-paste usage examples rendered on each component page — a
live preview plus the full source, at
`https://www.oks-ui.com/components//#recipe-`.
### Button (`/components/button`)
- **Variants** (`#recipe-variants`): Five visual weights, from a filled solid down to an inline link — reach for lighter variants as the action gets more secondary.
- **Semantic colors** (`#recipe-colors`): Colour communicates intent — primary for the main action, success/warning/danger for outcomes. All read from your theme tokens.
- **Sizes** (`#recipe-sizes`): Six size tokens from xs to xl. Pick by density — xs/sm for toolbars and tables, lg/xl for landing-page calls to action.
- **With icons** (`#recipe-icons`): Add a leading or trailing icon with startContent / endContent — spacing and sizing are handled for you. (Bring your own SVG components.)
- **Icon-only** (`#recipe-icon-only`): Set isIconOnly for a square control that holds just an icon — always pass an aria-label so it stays accessible.
- **Loading state** (`#recipe-loading`): isLoading swaps in a spinner and disables the button so it can't be double-submitted. Move the spinner with spinnerPlacement.
- **Full width** (`#recipe-full-width`): fullWidth stretches the button to its container — the norm for forms and mobile CTAs.
- **As a link** (`#recipe-as-link`): Pass as={Link} (or any element/component) and Button renders a real anchor — full button styling, correct link semantics, keyboard and right-click behaviour.
### Card (`/components/card`)
- **Header, body, footer** (`#recipe-anatomy`): Card composes three optional regions — CardHeader, CardBody, CardFooter — so structured content lines up consistently.
- **Hoverable** (`#recipe-hoverable`): isHoverable adds a subtle lift on hover — the cue that a card is interactive or leads somewhere.
- **Clickable card (as a link)** (`#recipe-clickable`): Wrap the whole card in a Link so the entire surface is one focusable target — the pattern for card grids that navigate.
- **KPI card** (`#recipe-kpi`): A compact metric tile — the building block of a dashboard row.
- **Elevation** (`#recipe-shadows`): Dial the shadow from flat to lifted with the shadow scale — match it to how much the card should stand off the page.
### Badge (`/components/badge`)
- **Notification count** (`#recipe-count`): Badge wraps a target and pins a count to its corner — the classic unread indicator on a bell or inbox icon.
- **Capped count** (`#recipe-max`): Pass max and any higher count renders as “max+”, so a busy counter never blows out its width.
- **Status on an avatar** (`#recipe-on-avatar`): A small dot badge on an avatar reads as presence — pair a green dot with a user image.
- **Semantic colors** (`#recipe-colors`): Colour the badge to match meaning — danger for errors, success for done, warning for attention.
- **Placement** (`#recipe-placement`): Pin the badge to any corner with placement — top-end is the default; move it to suit the target.
### Avatar (`/components/avatar`)
- **Image avatar** (`#recipe-image`): Pass src for a photo; name gives it an accessible label and an initials fallback if the image fails to load.
- **Initials fallback** (`#recipe-initials`): With no src, Avatar renders the name's initials — colour it with the color prop for variety across a list.
- **Sizes** (`#recipe-sizes`): Six size tokens (or a raw pixel number) — small for dense lists, large for profile headers.
- **Presence status** (`#recipe-status`): status adds an online/offline/dnd indicator dot — presence without a separate element.
- **Avatar group** (`#recipe-group`): AvatarGroup overlaps avatars and collapses the overflow into a “+N” once past max — the standard “who's on this” cluster.
- **Group with name tooltips** (`#recipe-group-tooltip`): Avatar's own tooltip prop wraps it in a Tooltip -- pass true (or just the prop with no value) to derive the label from name, or a string/object for full control. AvatarGroup clones its size/color/radius/... group defaults onto each Avatar before that wrapping happens, so tooltip composes with it with no extra wiring.
### Chip (`/components/chip`)
- **Variants** (`#recipe-variants`): Four weights — solid, soft, bordered, and a dot variant for status labels.
- **Semantic colors** (`#recipe-colors`): Soft chips make great status pills — colour them by meaning (paid, pending, failed).
- **With an icon** (`#recipe-with-icon`): startContent puts an icon before the label — handy for tags and categories.
- **Closable (removable)** (`#recipe-closable`): Pass onClose and Chip shows a × button — the building block of a filter/token input. Track the list in state and drop the chip on close.
- **With an avatar** (`#recipe-avatar-chip`): The avatar prop tucks a small image at the chip's start — a person or entity token.
### Alert (`/components/alert`)
- **Status colors** (`#recipe-statuses`): Colour maps to intent — success, warning, danger, info — and swaps the leading status icon to match.
- **Variants** (`#recipe-variants`): solid, soft, and bordered — soft is the everyday inline notice; solid draws maximum attention.
- **With actions** (`#recipe-with-actions`): The actions slot holds buttons — a confirm/dismiss inline with the message.
- **Dismissible** (`#recipe-closable`): isClosable adds a × and, when uncontrolled, hides the alert on click — the standard dismissible banner.
- **Custom icon** (`#recipe-custom-icon`): Override the default status icon with your own, or hide it entirely with hideIcon.
### Text Field (`/components/form-field-text`)
- **Basic text field** (`#recipe-basic`): A labelled input with helper text. Wrap fields in a Form so their values are collected and validated together.
- **Leading & trailing icons** (`#recipe-with-icons`): startIcon and endIcon sit inside the control — a search glyph, a status tick — without disturbing the input's own padding.
- **Prefix & suffix affixes** (`#recipe-affixes`): prefix and suffix render attached segments — a currency symbol, a unit, a fixed URL base — that are visually part of the field but never part of its value.
- **Declarative validation** (`#recipe-validation`): validation.rules covers the common cases — required, email, length, pattern — and Form shows the error per-field once it's touched.
- **Floating label** (`#recipe-floating-label`): labelPlacement="floating" starts the label inside the control and animates it up on focus or value — a tighter footprint that still keeps a real, associated label.
- **Visual variants** (`#recipe-variants`): Four surfaces for different densities — bordered by default, soft and filled for grouped forms, underlined for a minimal look.
### Textarea Field (`/components/form-field-textarea`)
- **Basic textarea** (`#recipe-basic`): Multi-line input with a fixed visible height. rows sets the starting line count.
- **Character counter** (`#recipe-length-counter`): showLengthCounter renders a live count against maxLength, so users can see how much room is left before they hit the limit.
- **Required with min length** (`#recipe-validation`): The same rules engine as every field — require the field and enforce a minimum length before submit succeeds.
- **Floating label** (`#recipe-floating-label`): A floating label works on the textarea too — it keeps a persistent, associated label while reclaiming the space a top label would take.
### Select Field (`/components/form-field-select`)
- **Single select** (`#recipe-single`): Pass options as { label, value } pairs. The custom popover is searchable and keyboard-navigable out of the box.
- **Multi-select** (`#recipe-multiple`): multiple turns the value into an array and renders each choice as a removable chip inside the trigger.
- **Options with icons** (`#recipe-with-content`): Each option can carry startContent — a flag, an avatar, a status dot — so the menu reads at a glance, not just as text.
- **Native select** (`#recipe-native`): native swaps the custom popover for the platform's own