Install and configure

Installation

npm install @antadesign/anta   # or pnpm / bun

Pin an exact version in package.json ("@antadesign/anta": "0.3.16") instead of a floating tag such as "latest".

Usage

import '@antadesign/anta/tokens.css'  // CSS custom properties
import '@antadesign/anta/reset.css'   // reset and typography defaults
import '@antadesign/anta/elements'    // registers <a-*> elements
import '@antadesign/anta/theme-antune.css' // optional Antune theme
import { Progress } from '@antadesign/anta'

<Progress value={42} label="Uploaded" hint="3 of 7" />

Full bundle

For a single minified Anta runtime and stylesheet, use the bundle pair instead of the separate tokens, reset, elements, and JSX imports:

import '@antadesign/anta/bundle.css'
import { Progress } from '@antadesign/anta/bundle'

<Progress value={42} label="Uploaded" hint="3 of 7" />

bundle registers every custom element and re-exports the JSX API. Its React peer dependency and Preact configuration are the same as the regular JSX entry.

What you import (and why)

Tokens, elements, and the JSX layer render a styled component. The reset is recommended; the reference theme is optional.

Load tokens.css before element CSS. Elements read its variables; without it, they render unstyled.

To use the optional reference palette, import theme-antune.css after the element registration import. It ships in @antadesign/anta; omit it to keep the seed-derived default palette or provide your own theme.

Cascade layers

Anta’s reset and element CSS use child layers inside @layer anta. Every Anta stylesheet reserves the same order, so granular stylesheets remain safe when a bundler loads them before tokens.css:

@layer base, anta, components, utilities;
@layer anta.reset, anta.components, anta.theme;

anta.theme lets the optional reference palette replace component formulas. The outer anta layer keeps its public cascade position.

To change that order, declare it in CSS loaded before any Anta stylesheet. The first declaration fixes a layer’s position:

/* your global.css, loaded before anta */
@layer reset, anta, my-components, utilities;

Token custom properties stay unlayered so they apply everywhere.

Gotcha: an unlayered hard reset defeats Anta’s element rules.

*, *::before, *::after { box-sizing: border-box; }
* { margin: 0; }

Unlayered styles beat layered ones regardless of specificity. This reset overrides Anta’s element defaults. Delete the duplicate, or put your reset in @layer base { … }; reset.css already applies the same universal reset in @layer anta.reset.

AI setup

Anta includes version-matched Markdown documentation in its npm package. Append this section to your application’s agent instruction file, such as AGENTS.md, CLAUDE.md, or your tool’s equivalent. Keep existing project rules:

## Anta

Before Anta UI work, read
`node_modules/@antadesign/anta/docs/index.md`
and the pages relevant to the task.
Verify component names, imports, props, and event signatures against the
installed documentation and TypeScript declarations. Do not infer Anta APIs
from similarly named components in other libraries.

The path is relative to the application directory where Anta is installed. Adjust it for your workspace or package-manager layout. Installing Anta does not modify your agent configuration.

For tools without local file access, provide the web documentation index and your installed Anta version. Web documentation may describe a newer release.

Registering elements

JSX wrappers render <a-*> tags. Register their classes before those tags reach the DOM. Registration needs HTMLElement, so the import is a no-op in Node.js and Worker threads.

import '@antadesign/anta/elements'  // auto-registers all elements

/elements registers everything. Per-element entries register one element and load only its CSS:

import '@antadesign/anta/elements/a-tooltip'  // only <a-tooltip> + its CSS
import '@antadesign/anta/elements/a-button'   // only <a-button> + its CSS

Both are idempotent, side-effect imports and safe during SSR.

Use a static import in your app entry, outside components and hooks:

// src/main.tsx (or wherever your root render lives)
import '@antadesign/anta/elements'
import { createRoot } from 'react-dom/client'
import App from './App'
createRoot(document.getElementById('root')!).render(<App />)

Module initialisation registers the classes before the first render, avoiding a flash of un-upgraded elements.

Why not useEffect(() => import('@antadesign/anta/elements'), [])? useEffect runs after paint and the import resolves later. The browser can paint unregistered elements first. useLayoutEffect is still asynchronous and warns during SSR hydration.

Choose the entry point for your runtime:

• Plain HTML or static sites: a <script type="module"> in the document head.
• Astro or Next.js: a client-only script. In Astro, use <script>import '@antadesign/anta/elements'</script>; in Next.js, import it from a 'use client' file.
• Worker-rendered UI: code that runs on the UI thread and initializes the DOM. A Worker has no HTMLElement.

Framework setup

React

Works out of the box.

Preact with compat

If your bundler aliases react to preact/compat, Anta works without setup.

Preact without compat

Call configure() before rendering any anta components:

import { configure } from '@antadesign/anta'
import { h, Fragment } from 'preact'
configure(h, Fragment)

TypeScript: typing raw <a-*> tags in JSX

JSX wrappers such as <Button> and <Progress> need no extra typing. Configure JSX only when you write raw <a-*> tags.

Option A (preferred) — point JSX types at Anta in tsconfig.json:

{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "@antadesign/anta" } }

Every a-* tag type-checks, standard HTML tags keep working, and importing @antadesign/stickers adds its tags automatically.

Option B — if jsxImportSource cannot change, merge Anta’s tag map into your JSX namespace with AntaIntrinsicElements (and StickerIntrinsicElements when needed):

import type { AntaIntrinsicElements } from '@antadesign/anta'
import type { StickerIntrinsicElements } from '@antadesign/stickers' // only if you use stickers

declare global {
  namespace JSX {
    interface IntrinsicElements extends AntaIntrinsicElements, StickerIntrinsicElements {}
  }
}

With @types/react 18+ and jsx: "react-jsx", JSX is module-scoped. Extend the react module instead:

import type { AntaIntrinsicElements } from '@antadesign/anta'

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements extends AntaIntrinsicElements {}
  }
}

Both options reject unknown tags and invalid props. New tags arrive with Anta upgrades; there is no per-tag list to maintain.

Raw web components (no JSX)

Elements also work in plain HTML. Registration loads their CSS; resolve the bare specifier with a bundler or import map.

<script type="module">
  import '@antadesign/anta/elements'
</script>

<a-progress value="42" max="100" tone="info"></a-progress>

Dark mode

For a page-wide dark mode, add dark to html. The body --bg-2 background then paints the browser canvas, and the root controls scrollbar colors:

<html class="dark">
  <body>
    <Progress value={50} />
  </body>
</html>

Use dark or light on another ancestor to scope its color scheme and palette.

Fonts

Without an optional theme, tokens.css defines system stacks in --sans-serif, --serif, and --monospace. Reference themes register hosted fonts and replace some of those same variables. Components and theme rules decide which stack to use. Theme-free components do not force font-specific stylistic sets or variable-font axes. tokens.css also sets 1rem to 15px.

Register application-owned fonts and redefine the variables in CSS loaded after the Anta styles and optional theme. This example uses separate Roman and Italic variable files:

@font-face {
  font-family: "App Sans";
  src: url("/fonts/app-sans-roman.woff2") format("woff2");
  font-style: normal;
  font-weight: 100 900;
}

@font-face {
  font-family: "App Sans";
  src: url("/fonts/app-sans-italic.woff2") format("woff2");
  font-style: italic;
  font-weight: 100 900;
}

:root {
  --sans-serif: "App Sans", sans-serif;
  --serif: Georgia, serif;
  --monospace: ui-monospace, monospace;
}

Place this application stylesheet after theme-antune.css or theme-antithesis.css, not before it. When all stylesheets are in the document head, the override applies before the first paint. Anta’s semantic italics (em, i, var, and dt) select the Italic face.

Variable slant

A variable font with a standard slnt axis can provide both instances. Expose it through font-style: oblique instead of setting slnt on italic elements:

@font-face {
  font-family: "App Variable";
  src: url("/fonts/app-variable.woff2") format("woff2");
  font-style: oblique 0deg 12deg;
  font-weight: 100 900;
  font-stretch: 75% 100%;
}

:root {
  --sans-serif: "App Variable", sans-serif;
}

The browser selects 0deg for normal text and 11deg for semantic italics. Use the range your font declares to avoid combining slnt with a synthetic oblique.

Browser support

Anta targets evergreen browsers and ships no baseline polyfills. Its floor is custom-element states, used throughout the components for their internal CSS state, alongside the Popover API:

This is Baseline 2024. Anta also relies on relative OKLCH, :has(), dvh, cascade layers, and constructable shadow DOM. Older browsers can fail hard, including :state() being unrecognized or showPopover() throwing. Gate Anta on your own support matrix when you support older browsers.

Two features progressively enhance with fallbacks: checkVisibility() falls back to getClientRects(), and typed CSS attr() supports raw <a-icon size> in Chrome 133+ and Safari 18.2+. Elsewhere use <Icon size> or --icon-size.