# Installation

> Add @azmr/ui to a React app in four steps, then follow the guide for your framework, whether Next.js, Vite, React Router or plain React.

Source: https://platform.azmara.io/docs/guide/installation

`@azmr/ui` is a React component library styled with Tailwind CSS v4. Adding it to an app is the same four steps in every framework. What differs is how each one runs Tailwind, so there is a guide for each.

## Pick your framework

| Your app uses                                         | Guide                                                                                    |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Next.js (App Router)                                  | [Install in Next.js](https://platform.azmara.io/docs/guide/install-nextjs.md)            |
| Vite                                                  | [Install in Vite](https://platform.azmara.io/docs/guide/install-vite.md)                 |
| React Router (framework mode, the successor to Remix) | [Install in React Router](https://platform.azmara.io/docs/guide/install-react-router.md) |
| React with another bundler, or none of the above      | [Install in plain React](https://platform.azmara.io/docs/guide/install-react.md)         |

If you would rather own the code than depend on a package, copy the components with the shadcn CLI: see [Copy the source with the shadcn CLI](https://platform.azmara.io/docs/guide/shadcn-registry.md). New to the library? [Why @azmr/ui](https://platform.azmara.io/docs/guide/why-azmr-ui.md) says what it is for and what it does not have yet.

## The four steps

1. **Install the packages.** `@azmr/ui` and `@azmr/core` together with React:

   ```bash
   pnpm add @azmr/ui @azmr/core react react-dom
   # or
   npm install @azmr/ui @azmr/core react react-dom
   ```

   `@azmr/core` is a **peer dependency**. Install it yourself so your app and `@azmr/ui` share one copy: two copies give incompatible `Signal` types. `motion` is an optional peer, needed only for the [`@azmr/ui/motion`](https://platform.azmara.io/docs/components/motion.md) entry.

2. **Set up Tailwind CSS v4** with your framework's plugin. `@azmr/ui` does not install Tailwind for you. See [Tailwind CSS setup](https://platform.azmara.io/docs/guide/tailwind.md) for what it needs and why.

3. **Import the stylesheet and the class lists** after Tailwind, in your global CSS. Add one class list for each entry you use:

   ```css
   @import "tailwindcss";
   @import "@azmr/ui/styles.css";
   @import "@azmr/ui/classes/button.css";
   ```

   Each list tells Tailwind exactly which of the package's classes to generate, so you add nothing to a Tailwind config and get CSS only for the components you use. `@import "@azmr/ui/classes.css"` generates every component's classes instead. Without a class list, components render unstyled. [Tailwind CSS setup](https://platform.azmara.io/docs/guide/tailwind.md#how-tailwind-finds-the-packages-classes) explains them.

4. **Use a component.** Import it from its own entry, for example `import { Button } from "@azmr/ui/button"`. Every component's import path is at the top of its [component page](https://platform.azmara.io/docs/components.md).

## What you need

- **React 18 or 19.**
- **Tailwind CSS v4.** Version 3 does not work: the stylesheets use v4 directives.
- **A Node.js version your framework supports.** The package itself supports Node 18 and newer. The guides below are built in CI on Node 24.

## Dark mode and density

The page follows the operating system's light or dark setting with no setup and no JavaScript. To let people choose, wrap the app in `ThemeProvider` and read the choice with `useTheme()`; each guide shows how. Density (`compact`, `comfortable`, `spacious`) works the same way. See [Theming](https://platform.azmara.io/docs/guide/theming.md) for everything the theme can do.

## How these guides stay correct

Each framework guide shows the real files of a small app, not snippets written for the page. CI packs `@azmr/ui` into a tarball, installs it into each of those apps as a new project would, type-checks and builds them, and then checks the output: the Button is rendered, the colour tokens are there, and Tailwind generated the package's classes from the class lists the app imports. A change that breaks a guide fails the build, and the guide always shows the files that were tested.

## Working on the packages themselves

To clone the repository and run the docs site locally, see [Set up the monorepo](https://platform.azmara.io/docs/guide/monorepo-setup.md).