@wearenotch/ui-react
v0.4.0
Published
React components for the Notch Design System
Downloads
180
Readme
@wearenotch/ui-react
React components for the Notch Design System.
Install
pnpm add @wearenotch/ui-react @wearenotch/tokens
# or
npm install @wearenotch/ui-react @wearenotch/tokensreact and react-dom (>=19) are peer dependencies.
On React 18? Pin to the
0.3.xline:"@wearenotch/ui-react": "~0.3.2". Versions0.4.0+require React 19 — see the migration note below.
Usage
Import the tokens stylesheet once in your app entry, then use components anywhere:
// app entry (e.g. src/main.tsx)
import '@wearenotch/tokens/css';
import '@wearenotch/ui-react/css';import { Button, Input, FormField } from '@wearenotch/ui-react';
export function SignIn() {
return (
<form>
<FormField label="Email" htmlFor="email">
<Input id="email" type="email" />
</FormField>
<Button variant="primary" type="submit">Sign in</Button>
</form>
);
}Dark mode
Dark mode is CSS-only — toggle the data-theme attribute on <html>:
document.documentElement.setAttribute('data-theme', 'dark');No JavaScript color switching, no provider — every component reads tokens that respond to data-theme="dark".
Components
35 components covering primitives, forms, feedback, navigation, layout, and data display:
Primitives Button, IconButton, Badge, Tag, Avatar, Spinner, Skeleton, Tooltip Forms Input, Textarea, Select, MultiSelect, Checkbox, Switch, Slider, FormField, FileUpload, DatePicker, RichTextEditor Feedback Alert, Notification, ProgressBar, EmptyState Navigation Tabs, Accordion, Breadcrumbs, Pagination, Stepper Layout Card, Modal, List, Carousel Data display Table, Chart
Conventions
- All components forward refs where applicable and spread unknown HTML attributes onto their root element.
- Sizes use
sm | md | lg. - Form controls expose
value/onChangeand acceptid,name,disabled, etc. - Every interactive component has an accessible name — pass a visible label or
aria-label.
Storybook
Browse all components and variants:
pnpm --filter @notch/storybook dev
# http://localhost:6006Migrating from 0.3.x (React 18)
Version 0.4.0 bumps the React peer dependency to >=19.0.0 and adopts the React 19 ref-as-prop pattern internally. No code changes are required in consumer apps — *Props interfaces are unchanged. The break is purely at the peer dependency level.
To migrate:
- Upgrade your app to React 19 (
react,react-dom,@types/react,@types/react-dom). - Bump
@wearenotch/ui-reactto^0.4.0. - If you were doing
forwardRef-style ref forwarding around our components, that still works —refis now a regular prop and is forwarded automatically.
If you can't upgrade React yet, stay on ~0.3.2. We will not backport new features to 0.3.x, but security fixes will land there if needed.
Scripts
pnpm --filter @wearenotch/ui-react build # build dist/
pnpm --filter @wearenotch/ui-react test # run vitest
pnpm --filter @wearenotch/ui-react type-check # tsc --noEmitLicense
MIT