arc-library

<p align="center">
  <a href="https://uiarc.dev">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/banner-dark.png">
      <source media="(prefers-color-scheme: light)" srcset="./.github/assets/banner-light.png">
      <img alt="Arc: React components and blocks with calm, crafted motion. Free and open source, install with shadcn." src="./.github/assets/banner-light.png" width="100%">
    </picture>
  </a>
</p>

<p align="center">
  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-111111?style=flat-square"></a>
  <a href="https://uiarc.dev/docs/installation"><img alt="shadcn registry: @uiarc" src="https://img.shields.io/badge/shadcn%20registry-%40uiarc-111111?style=flat-square"></a>
  <a href="https://github.com/kuratlielia/arc-library/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/kuratlielia/arc-library/ci.yml?branch=main&style=flat-square&label=CI"></a>
  <img alt="100 components" src="https://img.shields.io/badge/components-100-7747ff?style=flat-square">
  <img alt="22 blocks" src="https://img.shields.io/badge/blocks-22-7747ff?style=flat-square">
  <img alt="React 19" src="https://img.shields.io/badge/React-19-111111?style=flat-square">
</p>

<p align="center">
  <a href="https://uiarc.dev/docs/introduction"><b>Docs</b></a>
  &nbsp;·&nbsp;
  <a href="https://uiarc.dev/components"><b>Components</b></a>
  &nbsp;·&nbsp;
  <a href="#install"><b>Install</b></a>
  &nbsp;·&nbsp;
  <a href="https://uiarc.dev/docs/ai"><b>AI and MCP</b></a>
  &nbsp;·&nbsp;
  <a href="https://uiarc.dev/pro"><b>Pro</b></a>
</p>

Arc is a library of React components and blocks with calm, physical motion. Every item is plain source you own: CSS modules on a small set of design tokens, [Motion](https://motion.dev) for animation, keyboard support, and a reduced motion path for every animation. Install anything with the shadcn CLI or copy the files by hand. It works in Next.js and Vite, with or without Tailwind. This repository holds the free, open source part: **100 components and 22 blocks**, plus the design and motion tokens they share. Every one of them has a live preview at [uiarc.dev](https://uiarc.dev).

## Showcase

A few favorites, recorded live from [uiarc.dev](https://uiarc.dev). Items marked <sup>Pro</sup> are part of [Arc Pro](https://uiarc.dev/pro) and are not in this repository; everything else installs from here for free.

<table>
<tr>
<td width="50%" valign="top">
<a href="https://uiarc.dev/pro"><picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/assets/showcase/cover-flow-dark.webp">
<img alt="Cover flow: A depth rail of photos you can throw, with soft grounded shadows and a quiet reflection." src="./.github/assets/showcase/cover-flow-light.webp" width="100%">
</picture></a>
<br><a href="https://uiarc.dev/pro"><b>Cover flow</b></a> <sup><a href="https://uiarc.dev/pro">Pro</a></sup><br>
<sub>A depth rail of photos you can throw, with soft grounded shadows and a quiet reflection.</sub>
</td>
<td width="50%" valign="top">
<a href="https://uiarc.dev/components/donut-chart"><picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/assets/showcase/donut-chart-dark.webp">
<img alt="Donut chart: Arcs morph between datasets while the total rolls into the center." src="./.github/assets/showcase/donut-chart-light.webp" width="100%">
</picture></a>
<br><a href="https://uiarc.dev/components/donut-chart"><b>Donut chart</b></a><br>
<sub>Arcs morph between datasets while the total rolls into the center.</sub>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<a href="https://uiarc.dev/components/billing-toggle"><picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/assets/showcase/billing-toggle-dark.webp">
<img alt="Billing toggle: Monthly and yearly prices roll into each other, savings included." src="./.github/assets/showcase/billing-toggle-light.webp" width="100%">
</picture></a>
<br><a href="https://uiarc.dev/components/billing-toggle"><b>Billing toggle</b></a><br>
<sub>Monthly and yearly prices roll into each other, savings included.</sub>
</td>
<td width="50%" valign="top">
<a href="https://uiarc.dev/pro"><picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/assets/showcase/orbit-logos-dark.webp">
<img alt="Orbit logos: Integrations orbit your product mark. Filter them by category." src="./.github/assets/showcase/orbit-logos-light.webp" width="100%">
</picture></a>
<br><a href="https://uiarc.dev/pro"><b>Orbit logos</b></a> <sup><a href="https://uiarc.dev/pro">Pro</a></sup><br>
<sub>Integrations orbit your product mark. Filter them by category.</sub>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<a href="https://uiarc.dev/pro"><picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/assets/showcase/wallet-stack-dark.webp">
<img alt="Wallet stack: Fan a stack of cards and lift one out to see its activity." src="./.github/assets/showcase/wallet-stack-light.webp" width="100%">
</picture></a>
<br><a href="https://uiarc.dev/pro"><b>Wallet stack</b></a> <sup><a href="https://uiarc.dev/pro">Pro</a></sup><br>
<sub>Fan a stack of cards and lift one out to see its activity.</sub>
</td>
<td width="50%" valign="top">
<a href="https://uiarc.dev/components/line-chart"><picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/assets/showcase/line-chart-dark.webp">
<img alt="Line chart: Switch the range and the line redraws against the previous period." src="./.github/assets/showcase/line-chart-light.webp" width="100%">
</picture></a>
<br><a href="https://uiarc.dev/components/line-chart"><b>Line chart</b></a><br>
<sub>Switch the range and the line redraws against the previous period.</sub>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<a href="https://uiarc.dev/components/number-field"><picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/assets/showcase/number-field-dark.webp">
<img alt="Number field: Bounded steppers that say so when you reach the limit." src="./.github/assets/showcase/number-field-light.webp" width="100%">
</picture></a>
<br><a href="https://uiarc.dev/components/number-field"><b>Number field</b></a><br>
<sub>Bounded steppers that say so when you reach the limit.</sub>
</td>
<td width="50%" valign="top">
<a href="https://uiarc.dev/pro"><picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/assets/showcase/activity-rings-dark.webp">
<img alt="Activity rings: Daily goals sweep, count up and trace a second lap past 100%." src="./.github/assets/showcase/activity-rings-light.webp" width="100%">
</picture></a>
<br><a href="https://uiarc.dev/pro"><b>Activity rings</b></a> <sup><a href="https://uiarc.dev/pro">Pro</a></sup><br>
<sub>Daily goals sweep, count up and trace a second lap past 100%.</sub>
</td>
</tr>
</table>

## Contents

- [Showcase](#showcase)
- [Install](#install)
  - [Requirements](#requirements)
  - [With the shadcn CLI](#with-the-shadcn-cli)
  - [Copy and paste](#copy-and-paste)
- [Usage](#usage)
- [Theming](#theming)
- [Components](#components)
- [Blocks](#blocks)
- [AI tools](#ai-tools)
- [Troubleshooting](#troubleshooting)
- [How releases work](#how-releases-work)
- [Repository layout](#repository-layout)
- [Arc Pro](#arc-pro)
- [Contributing](#contributing)
- [License](#license)

## Install

### Requirements

- **React 19** with TypeScript
- **Next.js** (App Router) or **Vite**
- **[motion](https://www.npmjs.com/package/motion)** for animation. Some items also use [lucide-react](https://lucide.dev) or a [Radix UI](https://www.radix-ui.com) primitive; the CLI installs whatever an item needs.
- The `@/*` import alias (Next.js and shadcn set it up by default)

No Tailwind is required. Arc styles are CSS modules that read CSS variables.

### With the shadcn CLI

Register the `@uiarc` namespace once in `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json"
  }
}
```

Then add items by name. Local dependencies, such as the components inside a block, come along automatically:

```bash
npx shadcn@latest add @uiarc/button @uiarc/dialog
```

Every item also installs from its full URL, without touching `components.json`:

```bash
npx shadcn@latest add https://uiarc.dev/r/button.json
```

Your first install adds `arc-foundation` (design and motion tokens). Import it once at the root of your app:

```tsx
// app/layout.tsx (Next.js) or src/main.tsx (Vite)
import "@/components/arc/foundation.css";
```

<details>
<summary><b>Setting up a new project</b></summary>

<br>

**Next.js**

```bash
npx create-next-app@latest my-app
cd my-app
npx shadcn@latest init
```

Accept the default `@/*` import alias.

**Vite**

```bash
npm create vite@latest my-app -- --template react-ts
cd my-app
npx shadcn@latest init
```

Map `@/*` to `src` in `tsconfig.json` and `vite.config.ts`, as shadcn expects:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  }
}
```

```ts
import path from "node:path";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react()],
  resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
});
```

</details>

### Copy and paste

1. Install the shared packages: `npm install motion lucide-react`.
2. Copy `registry/foundation.css`, `registry/motion-tokens.ts` and `lib/motion-tokens.ts` from this repository into the same paths under your `@/` root, and import the CSS once at the root.
3. Copy the item's folder from `registry/components/<id>/` or `registry/blocks/<id>/`, keeping the path. Copied files keep this repository's layout and import each other through `@/`; the CLI install above rewrites that for you. Its `public/r/<id>.json` file lists every file and npm package it needs.

Each page on [uiarc.dev](https://uiarc.dev/components) also has a Manual tab with the exact files.

## Usage

The CLI puts