# Available Astryx Theme Packages and How to Switch Them

> Discover the seven Astryx theme packages like Y2K, Stone, and Matcha. Learn how to easily install and switch between these themes using the XDSTheme provider in your React app.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**Astryx ships seven ready-made theme packages (Y2K, Stone, Neutral, Matcha, Gothic, Chocolate, and Butter) that you install via npm and apply using the `<XDSTheme>` provider from `@astryxdesign/core/theme`, switching between them at runtime by passing different theme objects to the provider.**

The **facebook/astryx** repository provides a complete theming system for React applications built on StyleX. Each **Astryx theme package** bundles StyleX-compiled token sets, optional pre-built CSS, and font-loading recommendations into a consumable npm module under the `@astryxdesign` namespace.

## Available Astryx Theme Packages

Astryx maintains seven distinct themes in `packages/themes/<name>`, each published as `@astryxdesign/theme-<name>`. The following table summarizes the design focus of each package:

| Theme | Package name | Primary design focus |
|-------|--------------|----------------------|
| Y2K | `@astryxdesign/theme-y2k` | Playful periwinkle / holographic palette |
| Stone | `@astryxdesign/theme-stone` | Warm stone & slate, earthy neutrals |
| Neutral | `@astryxdesign/theme-neutral` | Minimal, system-font-only |
| Matcha | `@astryxdesign/theme-matcha` | Earthy green, custom typefaces |
| Gothic | `@astryxdesign/theme-gothic` | Dark-only atmospheric gothic |
| Chocolate | `@astryxdesign/theme-chocolate` | Rich brown / cozy beige |
| Butter | `@astryxdesign/theme-butter` | Soft pastel palette |

## Installing Astryx Theme Packages

Install any theme via npm using its scoped package name:

```bash
npm install @astryxdesign/theme-y2k

```

Replace `y2k` with `stone`, `neutral`, `matcha`, `gothic`, `chocolate`, or `butter` to install other variants.

## Applying a Theme with XDSTheme

According to the source code in [`packages/core/src/theme/index.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/index.ts), the `<XDSTheme>` provider accepts a theme object and injects the corresponding CSS custom properties into your component tree.

Import the **theme object** from the `built` entry point (pre-compiled distribution) and wrap your application:

```tsx
import { XDSTheme } from '@astryxdesign/core/theme';
import { y2kTheme } from '@astryxdesign/theme-y2k/built';

function App() {
  return (
    <XDSTheme theme={y2kTheme}>
      {/* your UI goes here */}
    </XDSTheme>
  );
}

```

If you are using the StyleX source compiler (`@astryxdesign/build`), import from the bare package path instead to allow tree-shaking and compilation:

```tsx
import { y2kTheme } from '@astryxdesign/theme-y2k';

```

### Adding Pre-built CSS (Optional)

When using the pre-built distribution, you can import the generated CSS file into a global stylesheet as shown in [`packages/themes/y2k/README.md`](https://github.com/facebook/astryx/blob/main/packages/themes/y2k/README.md):

```css
@import '@astryxdesign/theme-y2k/theme.css';

```

## Switching Themes at Runtime

Because `<XDSTheme>` accepts any theme object as a prop, you can switch **Astryx theme packages** dynamically using React state. The provider automatically re-renders with new token values and CSS classes.

```tsx
import { XDSTheme } from '@astryxdesign/core/theme';
import { y2kTheme } from '@astryxdesign/theme-y2k/built';
import { stoneTheme } from '@astryxdesign/theme-stone/built';
import { useState } from 'react';

export function ThemedApp() {
  const [theme, setTheme] = useState(y2kTheme);

  return (
    <>
      <button onClick={() => setTheme(theme === y2kTheme ? stoneTheme : y2kTheme)}>
        Switch Theme
      </button>

      <XDSTheme theme={theme}>
        {/* app content */}
      </XDSTheme>
    </>
  );
}

```

### Handling Dark-Only Themes

The Gothic theme forces dark mode regardless of system preference. As implemented in [`packages/themes/gothic/README.md`](https://github.com/facebook/astryx/blob/main/packages/themes/gothic/README.md), pass the `mode="dark"` prop to the provider to maintain consistent native scrollbar and form-control styling:

```tsx
import { XDSTheme } from '@astryxdesign/core/theme';
import { gothicTheme } from '@astryxdesign/theme-gothic/built';

function App() {
  return (
    <XDSTheme theme={gothicTheme} mode="dark">
      {/* UI */}
    </XDSTheme>
  );
}

```

## Loading Custom Fonts

Most themes (except **Neutral**) reference custom web fonts. Each theme's README in `packages/themes/<name>/README.md` specifies the required `<link>` elements for the HTML `<head>`. While optional, loading these fonts is recommended to achieve the intended visual design.

## Core Theme Implementation Files

The theming system relies on several key files in the repository:

- [`packages/core/src/theme/index.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/index.ts) — Exports the `<XDSTheme>` component and public provider API.
- [`packages/core/src/theme/useTheme.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/useTheme.ts) — Provides the `useTheme` hook for programmatic access to resolved token values.
- [`packages/core/src/theme/types.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/types.ts) — Defines TypeScript interfaces for theme objects (`DefinedTheme`, token overrides).
- [`packages/core/src/theme/tokens.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.ts) — Contains the core token resolver that powers CSS custom properties behind every theme.

## Summary

- Astryx provides seven official theme packages: Y2K, Stone, Neutral, Matcha, Gothic, Chocolate, and Butter.
- Install themes via `npm install @astryxdesign/theme-<name>` and import the theme object from `/built` (or the bare path for source compilation).
- Wrap your application with `<XDSTheme>` from `@astryxdesign/core/theme` and pass the theme object to apply it.
- Switch themes at runtime by changing the theme object passed to the provider using React state.
- Use `mode="dark"` for dark-only themes like Gothic to ensure consistent UI chrome.
- Import optional pre-built CSS files and custom fonts listed in each theme's README for complete styling.

## Frequently Asked Questions

### What are the available Astryx theme packages?

Astryx maintains seven official theme packages: Y2K (playful periwinkle), Stone (warm neutrals), Neutral (system fonts only), Matcha (earthy green), Gothic (dark-only atmospheric), Chocolate (rich browns), and Butter (soft pastels). Each is published as `@astryxdesign/theme-<name>` under `packages/themes/<name>` in the facebook/astryx repository.

### How do I switch between Astryx themes dynamically?

You switch themes by updating the `theme` prop passed to the `<XDSTheme>` provider. Store the current theme object in React state (or any state manager) and toggle between imported themes like `y2kTheme` and `stoneTheme`. The provider re-renders automatically, applying the new token values and CSS classes without requiring a page reload.

### Should I import from `/built` or the bare package path?

Import from `/built` (e.g., `@astryxdesign/theme-y2k/built`) when using the pre-compiled distribution to get the theme object immediately. Import from the bare path (e.g., `@astryxdesign/theme-y2k`) when using `@astryxdesign/build` with the StyleX source compiler, allowing the build system to tree-shake and compile the theme tokens during your application's build process.

### Do I need to import CSS files separately for Astryx themes?

Importing CSS is optional when using the pre-built distribution. If you want to include the generated CSS manually, add `@import '@astryxdesign/theme-<name>/theme.css'` to your global stylesheet. When using the source compiler path, StyleX handles the CSS injection automatically.