Installation

Set up Roadie in a React app.

Install the packages

Install the core package and component library:

pnpm add @oztix/roadie-core @oztix/roadie-components

Add the others as you need them:

Setup

1. Add font preconnect hints

Add these to your HTML <head> to reduce font loading latency:

<link rel="preconnect" href="https://assets.oztix.com.au" crossorigin />
<link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin />

2. Configure your CSS

In your main CSS entry point (such as globals.css or index.css), import Roadie's CSS. This single import includes Tailwind CSS v4, all design tokens, theme variables, and base styles:

@import '@oztix/roadie-core/css';

3. Enable component class scanning

Tailwind v4 ignores node_modules by default, so it won't see the class strings inside Roadie's dist. If you're using @oztix/roadie-components, add one import. It ships its own @source, so you never write a node_modules path:

@import '@oztix/roadie-core/css';
@import '@oztix/roadie-components/css';

Using widgets, charts, or the editor too? Add @oztix/roadie-widgets/css, @oztix/roadie-charts/css, or @oztix/roadie-editor/css as well. Each package's CSS registers only its own classes, so include every package you use. The React widget skins render Roadie components, so they need the components CSS too; the Vue skins don't:

@import '@oztix/roadie-core/css';
@import '@oztix/roadie-components/css';
@import '@oztix/roadie-widgets/css';
@import '@oztix/roadie-charts/css';
@import '@oztix/roadie-editor/css';

4. Mount RoadieProvider

Wrap your app once, at the root. RoadieProvider routes every href through your router, handles light and dark, shows the toasts any component adds, and groups tooltips so a neighbour opens straight away.

// app/providers.tsx
'use client'

import type { ReactNode } from 'react'

import NextLink from 'next/link'

Render <Providers> around {children} in your root layout. The file is a client component because a Link component can't cross from the server, and your layout and pages stay server components. Each part takes its usual options, and false leaves that part out:

<RoadieProvider
  link={NextLink}
  theme={{ followSystem: true }}
  toast={{ position: 'top-end', timeout: 6000 }}
>
  {children}

Placing providers yourself

Every part is still exported on its own, and the nearest provider wins. This is what RoadieProvider mounts:

'use client'

import type { ReactNode } from 'react'

import NextLink from 'next/link'

Place them yourself when one root doesn't fit:

• Widgets in a page you don't own. Mount only what the widget uses, inside its own root, and leave the theme to the host page.
• Scoped regions that need something different, such as a collection route with its own accent (<ThemeProvider accentColor={…}>) or a panel with its own Toast.Provider and viewport.
• Multiple React roots. Context doesn't cross roots, so each root needs providers. Mount the theme in one root only, since it writes to the document, and give the others <RoadieProvider theme={false} toast={false}> or just the providers they use.

Moving to RoadieProvider

Replace your root's RoadieLinkProvider, ThemeProvider, and Toast.Provider with one RoadieProvider, and move their props across: Link becomes link, the theme's props go in theme, and the toast provider's props and the viewport's position go in toast. Nothing else changes, and the individual providers keep working.

Keep an individual provider only for a deliberate scoped override. In development, Roadie warns when a RoadieProvider sits inside another one, or when a ThemeProvider or Toast.Provider it already mounts wraps it or sits straight inside it.

Usage

Using components

Import each component from its own subpath. Components use the intent and emphasis props for styling:

import { Button } from '@oztix/roadie-components/button'

function MyComponent() {
  return (
    <div className='grid gap-4'>
      <h1 className='text-display-ui-3 text-strong'>Welcome</h1>

Using intent and emphasis

The intent prop sets a component's colour:

<Button intent='neutral'>Default action</Button>
<Button intent='accent'>Primary action</Button>
<Button intent='danger'>Delete</Button>
<p className='intent-success'>Operation complete</p>

The emphasis prop controls the visual weight:

<Button emphasis='strong'>Strong button</Button>
<Button emphasis='normal'>Normal button</Button>
<Button emphasis='subtle'>Subtle button</Button>
<p className='text-subtle'>Secondary text</p>

Using Tailwind classes for layout

Use standard Tailwind CSS classes for layout, spacing, and custom styling:

function MyComponent() {
  return (
    <div className='grid gap-4 p-4'>
      <div className='grid grid-cols-2 gap-2'>
        <div>Item 1</div>
        <div>Item 2</div>

Adding custom classes to components

All components accept a className prop for additional Tailwind classes:

<Button className='w-full' intent='brand' emphasis='strong'>
  Full width button
</Button>
<p className='max-w-prose text-lg'>
  Constrained width text block.
</p>

Building with AI

Each package ships a roadie.manifest.json that coding agents read, and a Claude Code plugin teaches agents to build with Roadie. Building with AI covers both.

Next steps

• Browse the components
• Learn the design tokens
• Catch Roadie mistakes at lint time with the lint plugin
• Set up Claude Code and other agents in Building with AI