Skip to content

Installation

Get Ritla UI

Set up a project with the Ritla CLI, add components as source you own, and use your license key. The shadcn CLI works too.

Ritla UI installs as source. The CLI copies each component into your project, installs what it depends on and sets up the theme tokens once, so the code is yours to read and change.

Requirements#

A React app on Next.js or Vite, Tailwind CSS v4, Node 20 or later, and an import alias such as @/* in tsconfig.json.

Works in new and existing apps#

Ritla UI works in new and existing apps. The default install adds the theme beside Tailwind's defaults and changes none of your classes: p-4, gap-6, bg-red-500, text-sm, rounded-lg, shadow-md, dark: and rtl: render exactly as they did before.

Ritla UI's utilities use names Tailwind does not, so the two sets never meet:

Your classes, unchangedRitla UI's, beside them
p-4, gap-6p-space-16, gap-space-24
bg-red-500bg-surface-default, bg-red-normal
text-smtext-body-14
shadow-mdshadow-elevation-md
dark:theme-dark:
rtl:, ltr:dir-rtl:, dir-ltr:

The theme ships nothing global either: no rule on html, body or :root sets your font, letter spacing or focus ring. Your pages look as they did, and the components look as they do in these docs. Teams that want Ritla UI's scale and nothing else can opt into strict mode.

One exception to check: if your own @theme already defines a key with one of Ritla UI's exact names, such as a surface-default background color or --radius-8, the two share that name and one overrides the other. Rename yours out of those names. Tokens lists them.

Set the project up#

npx ritla init

init detects your framework, Tailwind version and import alias, writes ritla.json, installs @ritla/core (free) and imports its styles into your global stylesheet. With a license key set, it also installs the default theme's tokens.

It asks one question:

text
How does your app turn dark mode on?  1. class  a "dark" class on <html> (shadcn; next-themes with attribute="class")  2. data-theme  a data-theme="dark" attribute (next-themes by default)  3. system  the operating system setting (prefers-color-scheme)Choose 1-3 [1, the default]:

Enter takes the default, class. If your stylesheet already defines @custom-variant dark, the default follows it instead. To answer without the prompt, pass --dark class, --dark data-theme or --dark system. Outside a terminal, in CI for example, init takes the default without asking. The answer is saved in ritla.json, so later add and update runs keep it, and npx ritla init --dark <answer> changes it.

Then a second question:

text
Use Ritla's fonts or your app's font?  1. ritla  Ritla UI's fonts: Geist and IBM Plex Sans Arabic, per language  2. app  your app's font: the components inherit it from the pageChoose 1-2 [1, the default]:

ritla writes nothing: the components carry Ritla UI's fonts themselves, and with Next.js, npx ritla add fonts sets them up. app adds a short @theme inline block after the imports, so font-family-body and font-family-display inherit your page's font, while font-family-numeric keeps Ritla UI's figures so digits stay aligned. With app, make sure your app's font stack has an Arabic face, or Arabic falls back to a system font. --font ritla or --font app answers without the prompt, outside a terminal init takes the default, and the answer is saved in ritla.json as font. To name one font for every component instead, see Fonts.

Each switch has a file that holds the theme's dark colors and defines the theme-dark: variant: ritla-dark-class.css, ritla-dark-attr.css and ritla-dark-system.css. Your answer decides which one init imports, so the components turn dark on the same switch as the rest of your app. The default is the .dark class. See Dark mode.

Your global stylesheet then imports the theme in this order:

css
@import "tailwindcss";@import "../lib/ritla/ritla-strict.css";   /* strict only */@import "@ritla/core/styles.css";@import "../lib/ritla/ritla.css";@import "../lib/ritla/theme.css";@import "../lib/ritla/ritla-dark-class.css"; /* or -attr / -system */

Every component reads the theme, so install it before the first one: npx ritla init with your license key set, or npx ritla add style. Skip it and the components land as unstyled markup, with no error.

Strict mode#

Strict mode is opt-in. It is for a new app, or a dedicated layout, that should use Ritla UI's scale and nothing else:

npx ritla init --strict

In a project that is already set up, npx ritla add style-strict does the same. It adds ritla-strict.css. Its recommended place is right after Tailwind and before the theme's own files, and it also works last, because it declares the theme's values again after its reset. It does two things the default install never does:

  • Resets Tailwind's defaults. Tailwind's colors, spacing, radii, shadows, blurs, fonts and font weights, type sizes, line heights, letter spacing, containers, breakpoints and easings are removed, so bg-red-500, p-4 or text-sm produce no CSS and only the theme's names do.
  • Adds the base styles. The page takes the theme's font family in English and in Arabic, no letter spacing in Arabic, the theme's focus ring on every focused element, and the theme's duration and easing on a bare transition.

Keep it to new apps and dedicated layouts: in an existing app, the classes it removes are the ones that app already uses.

Add your license key#

Ritla UI components are paid. Copy your key from your dashboard (Licenses) into .env.local, which must be git-ignored:

RITLA_LICENSE_KEY=your-key

The CLI reads it from the environment, then .env.local, then .env, and sends it only to ritla.app, over HTTPS: a ritla.json that names another registry gets no key unless you declare that registry trusted with RITLA_REGISTRY_TRUST in your own shell, never in a project file. It never writes the key anywhere. In CI, set RITLA_LICENSE_KEY as a pipeline secret. npx ritla login checks the setup.

Add components#

npx ritla add phone-input card-details

add fetches each component and everything it depends on, writes the source into your project (you own it), installs the npm packages it needs, and merges its styles. Files you have edited are kept unless you pass --overwrite. Every component page lists its exact command under Installation.

Stay up to date#

npx ritla diff shows what changed in the registry since you installed; npx ritla update takes the changes into files you have not edited. The CLI reference has every command and option.

Errors you may see#

  • "... is part of Ritla UI" (401): no key was sent. Set RITLA_LICENSE_KEY.
  • "This license key is not valid", "has expired" or "does not include ..." (403): check the key in your dashboard.
  • "Too many requests" (429): wait the number of seconds shown.

The free part: @ritla/core#

@ritla/core is free and MIT licensed, and init installs it for you. On its own: npm install @ritla/core (it needs React 18 or later). It holds the pieces every component builds on: <Ltr> and <Isolate> for bidi islands, formatNumber, toNumerals and parseNumber for explicit digit sets, <Mirror> and isDirectionalIcon for direction-aware icons, and @import "@ritla/core/styles.css" for the Arabic typography defaults.

Using shadcn instead#

The registry speaks the shadcn format, so projects that already run on the shadcn CLI can install Ritla UI with it. With shadcn 4 or later, npx shadcn add @ritla/style installs the theme with the .dark switch. See Using shadcn instead.

Renamed before release#

Ritla UI's variables, provider and a few utilities were renamed before its first public release (2026-10-28), so that it could install beside Tailwind. A fresh install has nothing to do. An install from before that date follows Migration, which lists every rename.