Guide · Open source

How to use Astryx: install, theme and run components

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Astryx is an open source design system: a set of pre-built, accessible React components, themes and a CLI that help teams build consistent user interfaces. This guide shows you how to install it, set up a theme, and find and use components. By the end you will have a working setup in a React 19 project and know where to look for component docs.

Astryxmeta/astryx · ★ 13.8k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm your project uses React 19 or later and that you have Node.js and a package manager installed.
2Install packages. Run the npm, pnpm or yarn command to add @astryxdesign/core, a theme and @stylexjs/stylex, then add @astryxdesign/cli as a dev dependency.
3Add the CLI script. Add the astryx script to package.json so the CLI runs from your project's own install.
4Import the styles and theme. Add the CSS imports and theme provider described in the @astryxdesign/core README.
5Browse components. Run npm run astryx -- component --list to see the available components.
6Customize the look. Change CSS theme variables or use className to adjust components to your design.

What you need before you install Astryx

Astryx requires React 19 or later. The react and react-dom packages are peer dependencies of @astryxdesign/core, so your project needs them at that version.

The README says Astryx is currently in Beta, so plan for possible API changes. It also states that Astryx uses Node.js, but does not give a specific Node version for users.

React 19 or later
Node.js (the README does not specify a version for users)
A package manager: npm, pnpm or yarn

Install Astryx, a theme and the CLI

Install the core package, a theme and the peer dependency StyleX with your package manager. Then add the CLI as a dev dependency. The README lists commands for npm, pnpm and yarn.

npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
npm install -D @astryxdesign/cli

Set up the CLI so it runs reliably

You can install the CLI globally so the astryx command works in any folder. In a project, it still runs that project's own version. The README notes that global mode is useful, and that using both project and global install is recommended.

For reliable access, add a script to package.json. This avoids path errors when AI assistants or new developers call the CLI directly.

Global install: run the global command once on your computer
Project script: run the CLI through npm run astryx

npm i -g @astryxdesign/cli

"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}

Use the CLI to list components

Once the script is in place, you can ask the CLI for the list of components. The README gives this example command. Use the CLI docs for other commands, since the README only names templates, scaffolding, themes and codemods as CLI features.

npm run astryx -- component --list

Configure the theme and styles

The simplest setup uses a few CSS imports and a theme provider, with no build plugin and no PostCSS or Babel config. A theme is a set of CSS custom property overrides, so designers can change the look without forking or wrapping component source.

Astryx styles are authored with StyleX, but you do not need to know StyleX to use it. You can override styles with className using Tailwind, CSS modules or plain CSS. For setup in Next.js, Tailwind, Vite or from a CDN, see the @astryxdesign/core README.

Pick one of the seven themes: neutral, butter, chocolate, matcha, stone, gothic or y2k
Override CSS custom properties to match your brand
Use className to adjust individual components

Know what each package does

Astryx is split into several packages. Core holds the components, theme system and utilities. The CLI provides component docs, templates, scaffolding, themes and codemods. The build package holds plugins for StyleX source builds. Theme packages follow the @astryxdesign/theme-* pattern.

Two packages, vega and charts, are published only under the canary dist-tag, and the README says there is no stable release yet.

@astryxdesign/core: components, theme system, utilities
@astryxdesign/cli: docs, templates, scaffolding, themes, codemods
@astryxdesign/build: build plugins for StyleX source builds
@astryxdesign/theme-*: ready-made themes

What people use it for

Building React interfaces from a shared set of accessible components
Customizing brand colours and look through CSS theme variables
Giving AI coding assistants the same documented components as developers
Copying component source into your own project to modify it

Frequently asked questions

Is Astryx free to use?

Yes. Astryx is released under the MIT licence, as stated in the README. You can use, modify and distribute it under those terms.

What are the requirements for Astryx?

Astryx requires React 19 or later, with react and react-dom as peer dependencies of @astryxdesign/core. The README also mentions Node.js but does not give a version for users.

How do I install Astryx?

Run npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex, then npm install -D @astryxdesign/cli. pnpm and yarn commands are also listed in the README.

Is Astryx ready for production?

The README says Astryx is currently in Beta. Because of this, it does not promise a stable long-term API, so check its status before depending on it for a long-lived project.

How is Astryx different from Material UI, Chakra UI, Mantine or shadcn/ui?

Astryx is a React design system with 150+ accessible components, themes, dark mode and a CLI. The README stresses open internals, swizzle for copying component source, and tooling shared by people and AI assistants. This guide does not compare features or performance with the other libraries, so review each one against your needs.

Do I need to know StyleX to use Astryx?

No. The README says StyleX is used to author Astryx styles but is invisible to consumers. You can override styles with className using Tailwind, CSS modules or plain CSS.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Astryx suits React teams that want a ready-made accessible component library, designers who want to customize through CSS variables, and teams using AI coding assistants with documented components. It is a poor fit if you need a stable long-term API while it is in Beta, use a React version earlier than 19, or want a design system that needs no installing or theme setup.

Install options & downloads