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.

Not on npm yet

@syntara/react and @syntara/tokens are published in Phase 6. Until then, copy the files by hand. The npm steps below show how the packages will work.

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 the packages

pnpm add @syntara/react @syntara/tokens

@syntara/react has the components and ThemeScope. @syntara/tokens has the token CSS for every tenant. React and React DOM are peer dependencies; React Aria and the icons come with the package.

Import the CSS once

At your app root — app/layout.tsx in Next.js, src/main.tsx in Vite — import the tokens and the component styles.

app/layout.tsx
import '@syntara/tokens/dist/syntara.css';
import '@syntara/react/styles.css';

dist/syntara.css holds every tenant, each scoped to [data-syntara-theme="<id>"]. If your app only ever shows one brand, import @syntara/tokens/dist/<id>/tokens.css instead; it puts that tenant on :root.

Wrap your app in a ThemeScope

import { Button, ThemeScope } from '@syntara/react';

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

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.