Skip to content

Installation

Add Syntara to a React project with npm, or by copying the files.

Syntara installs two ways: from npm, or by copying a component’s source files into your project (ADR-011). Both give you the same components and the same tokens. Every component page has the exact steps.

You need React 19 and a bundler that handles CSS — Next.js and Vite both do out of the box. Syntara doesn’t use Tailwind, so it works with or without it.

With npm

Install everything

pnpm add syntara

One package brings it all: the components and ThemeScope, the icon set, the token CSS for every tenant and the theme engine. React and React DOM are peer dependencies.

Import the CSS once

At your app root — app/layout.tsx in Next.js, src/main.tsx in Vite — import the one stylesheet: every tenant's tokens, then the component styles.

app/layout.tsx
import 'syntara/styles.css';

The tokens are scoped to [data-syntara-theme="<id>"], one block per tenant.

Wrap your app in a ThemeScope

import { Button, ThemeScope } from 'syntara';

export default function App() {
  return (
    <ThemeScope theme="vela" scheme="dark">
      <Button>Continue</Button>
    </ThemeScope>
  );
}

Icons come from syntara/icons and the theme engine from syntara/theme-engine.

One piece at a time

syntara is a bundle of the separate packages, which are still published on their own: @syntara/react (components), @syntara/tokens (token CSS), @syntara/icons and @syntara/theme-engine. Install them separately when you only need one, for example the tokens in an app that isn't React:

pnpm add @syntara/react @syntara/tokens
import '@syntara/tokens/dist/syntara.css';
import '@syntara/react/styles.css';

If your app only ever shows one brand, import @syntara/tokens/dist/<id>/tokens.css instead of dist/syntara.css; it puts that tenant on :root. Each component also has its own entry point, e.g. import { Button } from '@syntara/react/ui/button'.

By hand

Every component page has a Manual tab with the full source of each file.

  1. Install the npm packages the component lists — usually react-aria-components (44 components) and @syntara/icons (23); the two date components also need @internationalized/date.
  2. Copy its .tsx and .module.css files into one folder, such as components/ui.
  3. Copy any Syntara components it uses into the same folder. Files import each other as ./button, so the folder can live anywhere.
  4. Load a token file once at your app root. Take one from @syntara/tokens, or copy the CSS export on the Themes page.

The files are yours from then on. They are CSS Modules that read --syntara-* variables, and nothing else.

Set the theme

Token CSS keys off three attributes on one element — <html> for the whole app, or a ThemeScope for part of it.

<html data-syntara-theme="vela" data-syntara-scheme="auto" data-syntara-density="compact">

With a single tenant’s tokens.css, the tenant is already on :root. Put the scheme and density attributes on <html>. To give regions of a page different tenants or schemes, load syntara.css and pass theme to each ThemeScope.

See Theming, Dark mode and Density for the rest.