Skip to content

Installation

Add a component. Keep the source. Everything you need comes with it, including styles, fonts, and dependencies.

1. Set up your project

Start with React 19, TypeScript, and Tailwind CSS 4. Initialize shadcn once, or skip this step if your project already uses it.

Terminal
pnpm dlx shadcn@latest init

In Vite, use Tailwind’s Vite plugin. If your project uses @tailwindcss/postcss instead, set its optimize option to false so Vite can resolve imported font URLs before minifying the CSS. Next.js can keep its standard PostCSS configuration.

2. Add a component

Terminal
pnpm dlx shadcn@latest add https://react-toolbox.io/r/button.json

The CLI copies the component and its dependencies into your project. Replace button with another component name, or all for the full collection.

3. Use it

tsx
import { Button } from '@/components/ui/material/button';

export default function Example() {
  return <Button primary raised label="Hello, Material" />;
}

Use your configured UI alias if it differs from @/components/ui. Component entries load their styles automatically. Add 'use client' to examples that use state or event handlers in Next.js.

Fonts and first paint

Roboto and Material Icons are included and served with your app. No font service is required. The default Roboto styles use font-display: swap, which can change the text’s appearance when the font arrives.

In Next.js, prefer next/font/google. It downloads the font at build time, then serves it from your own deployment with preloading and an adjusted fallback. Visitors make no requests to Google.

tsx
import { Roboto } from 'next/font/google';
import type { ReactNode } from 'react';
import './globals.css';

const appRoboto = Roboto({
  weight: ['400', '500'],
  subsets: ['latin'],
  variable: '--font-app',
  fallback: ['Helvetica', 'Arial', 'sans-serif'],
  display: 'optional',
});

export default function RootLayout({ children }: { children: ReactNode }) {
  return <html lang="en" className={appRoboto.variable}><body>{children}</body></html>;
}
css
:root {
  --preferred-font: var(--font-app);
}

body {
  font-family: var(--preferred-font);
}

Remove the two @fontsource/roboto imports from your copied material/foundations/styles/fonts.css to avoid loading Roboto twice. Keep its Material Icons import: built-in calendar arrows, scrollable tabs, and sorted table headers still use it. If you already load a font, reuse its CSS variable instead of adding another loader.

display: 'optional' prevents a late font swap: on a slow first visit, the fallback can stay in place for that page load. A hosted font alone does not prevent flicker. Include the weights and language subsets your app needs.

If your build must work offline or use pinned font files, next/font/local provides the same loading controls with the included Fontsource files. Other frameworks can use local @font-face rules with font-display: optional and preload critical fonts.

React Toolbox reserves space for font icons while they load. For icons that must appear on first paint, pass an SVG element to the component’s icon prop; font icons still need their font download to render.

Use your router for navigation

The earlier Link and Navigation components are retired. React Toolbox supplies Material surfaces and controls; routing stays with your application. In Next.js, use Link from next/link; elsewhere, use your router’s link or a native anchor.

tsx
import Link from 'next/link';
import { List, ListItem } from '@/components/ui/material/list';

export function ProjectNavigation({ current }: { current: string }) {
  return (
    <nav aria-label="Projects">
      <List selectable ripple>
        <ListItem
          caption="Projects"
          primaryAction={<Link href="/projects" aria-current={current === '/projects' ? 'page' : undefined} />}
        />
      </List>
    </nav>
  );
}

Passing the link as primaryAction keeps the whole row interactive and keyboard accessible. Mark the selected destination with aria-current="page".

Use the @react-toolbox shortcut

Add this registry to your existing components.json, keeping the rest of its configuration:

components.json
{
  "registries": {
    "@react-toolbox": "https://react-toolbox.io/r/{name}.json"
  }
}
Terminal
pnpm dlx shadcn@latest add @react-toolbox/button

The shortcut requires this configuration until React Toolbox is listed in shadcn’s public registry directory. The full URL requires no namespace configuration.

Make changes. Keep them.

Public entries live in material/, alongside existing shadcn components. Shared helpers live in material/foundations/. Edit them to fit your project.

Already using the earlier toolbox-prefixed entries? Add the components again and update imports to material/button, material/theme, or the corresponding family. The CLI leaves old entry files in place; remove them after migrating your imports.

The installed source is yours; there is no package version to upgrade. To update, commit your edits, run the add command again, and review each overwrite prompt against the diff before replacing a customized file. The source releases carry the notes and migration steps for the behavior changes to expect in that diff, and pin every dependency to one reviewed edition.

Convenience and compound components now share their interaction primitives. When updating an older copy, review the behavior migration guide for focus timing, keyboard navigation and event cancellation changes.

Next: Theming →