@joyful.tools/neob
v2.3.1
Published
Accessible React 19 components with a bold Neo-Brutalist design system
Readme
neob
A React 19 component library with high-contrast styling and expressive motion.
neob provides accessible, design-system-compliant UI components built on Base UI. It handles keyboard navigation, focus management, and ARIA attributes with high-contrast layouts, spring animations, and built-in dark/light mode support.
Installation
Install neob from npm using your favorite package manager:
# Using bun (recommended)
bun add @joyful.tools/neob
# Using npm
npm install @joyful.tools/neob
# Using pnpm
pnpm add @joyful.tools/neobThe same release is also published to GitHub Packages as @joyful-tools/neob. Add the registry and a GitHub token with read:packages permission to your project or user .npmrc:
@joyful-tools:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}Then install the GitHub Packages build:
bun add @joyful-tools/neobPeer Dependencies
Ensure the React peer dependencies are installed:
# Using bun
bun add react react-dom
# Using npm
npm install react react-domUsage
Import components and the global stylesheet directly at the root of your application. The stylesheet is always an explicit import, regardless of whether components use root or granular imports:
import { Button, Card, Dialog } from '@joyful.tools/neob';
import '@joyful.tools/neob/dist/index.css';Granular Imports (Tree-Shaking)
To reduce your bundle size, you can import components individually. The global stylesheet is still required once at the application root:
import '@joyful.tools/neob/dist/index.css';
import { Button } from '@joyful.tools/neob/button';
import { Card } from '@joyful.tools/neob/card';React Actions and optimistic controls
Mutation-capable components expose one action prop. Selection controls render the proposed value immediately, queue rapid Actions in order, and commit uncontrolled state only after success. Command buttons disable themselves and expose data-pending and aria-busy while their Action runs.
import { Button, Checkbox, type Action } from '@joyful.tools/neob';
const savePreference: Action<[checked: boolean]> = async (checked) => {
setChecked(checked); // Keep controlled state synchronized before awaiting.
await savePreferenceToServer(checked);
};
<Checkbox checked={checked} action={savePreference} />;
<Button action={saveChanges}>Save changes</Button>;Legacy mutation callbacks and loading flags were removed. Migrate onValueChange, onCheckedChange, onPressedChange, onConfirm, setPage, and upload/complete callbacks to action; replace Button.isLoading with an async Button or form Action. Text input remains urgent through DOM-style callbacks such as onChange and onInput.
When a controlled update must happen after an await, wrap that update in a nested startTransition, because React does not currently retain the async transition context. Rejected Actions propagate to the nearest Error Boundary. Suspense fallback placement remains under application control.
Tailwind CSS v4 Configuration
neob leverages Tailwind CSS v4 for styling. To make custom neob CSS classes and themes available in your application, configure Tailwind to inspect the package:
@import 'tailwindcss';
/* Ensure Tailwind compiles neob classes from node_modules */
@source "../node_modules/@joyful.tools/neob/dist/**/*.{js,cjs}";Dark & Light Mode
neob supports dynamic dark mode out-of-the-box. The dark mode theme is class-based and will activate when the .dark class is applied to any parent element (e.g., <html> or <body>):
// Enable dark mode
document.documentElement.classList.add('dark');
// Disable dark mode
document.documentElement.classList.remove('dark');When active, color tokens automatically shift to their dark variant.
Apply neo-theme-root to the application shell when you want neob to provide the page background, foreground, font rendering, and theme defaults. Apply neo-app-shell separately only when the application intentionally needs overscroll containment.
Development & Documentation
To run the Storybook server locally for interactive documentation, testing, and component previews:
bun run storybookRefer to the available package scripts for testing and linting:
bun run check # Run linting, typechecking, and storybook tests
bun run build # Build the library bundle