# What Are the Core Components of Astryx? A Complete Guide to the UI Library

> Discover Astryx core components. Explore reusable UI primitives for basic elements, layout, forms, data display, navigation, and utility hooks. Your complete guide to the Astryx UI library.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: getting-started
- Published: 2026-08-03

---

**Astryx core components are a set of reusable UI primitives organized into six functional families—Basic UI primitives, Containers & layout, Form controls, Data display, Navigation & menus, and Utility hooks—all living in the `packages/core` package and documented in companion `*.doc.mjs` files.**

The Astryx design system, developed by Facebook (Meta), provides a framework-agnostic foundation for building internal tools and products. The core component library in `@astryxdesign/core` delivers consistent, theme-aware UI elements powered by **StyleX** for styling and following standardized prop-driven API conventions. Every component resides in its own folder under `packages/core/src` with TypeScript definitions and comprehensive documentation.

## Basic UI Primitives

The foundational building blocks of any Astryx interface live in `packages/core/src` and export essential visual elements.

### Button, Badge, Avatar, and Text Elements

These components handle the most common UI needs with minimal configuration:

- **`Button`** — Primary action triggers with `primary`, `secondary`, and `tertiary` variants (`packages/core/src/Button/Button.doc.mjs`)
- **`Badge`** — Status indicators and labels with contextual color schemes (`packages/core/src/Badge/Badge.doc.mjs`)
- **`Avatar`** — User profile images with fallback initials (`packages/core/src/Avatar/Avatar.doc.mjs`)
- **`Text`** and **`Heading`** — Typography hierarchy with theme-consistent sizing
- **`Kbd`**, **`Divider`**, and **`Blockquote`** — Specialized inline elements for documentation and command palettes

Each primitive accepts theme tokens as props and renders with StyleX-generated class names for zero-runtime overhead.

## Containers & Layout Components

Structural components manage spacing, layering, and responsive organization of content.

### Card and Dialog Systems

The **Card** component provides a composable container with named subcomponents:

```tsx
import { Card } from '@astryxdesign/core';
import { Button } from '@astryxdesign/core';
import { Avatar } from '@astryxdesign/core';

export function ProfileCard() {
  return (
    <Card>
      <Card.Header>
        <Avatar src="/images/jane.png" alt="Jane Doe" />
        <Card.Title>Jane Doe</Card.Title>
      </Card.Header>

      <Card.Body>
        <p>Product manager, loves data visualisation and clean UI.</p>
      </Card.Body>

      <Card.Footer>
        <Button variant="primary">Message</Button>
        <Button variant="secondary">Follow</Button>
      </Card.Footer>
    </Card>
  );
}

```

Card source: `packages/core/src/Card/Card.doc.mjs`

### Overlay and Navigation Containers

| Component | Purpose | Source |
|-----------|---------|--------|
| `Dialog` | Modal windows with focus trapping and backdrop | `packages/core/src/Dialog/Dialog.doc.mjs` |
| `Overlay` | Semi-transparent backdrops for layered UI | `packages/core/src/Overlay/Overlay.doc.mjs` |
| `SideNav` | Persistent or collapsible navigation rail | `packages/core/src/SideNav/SideNav.doc.mjs` |
| `Toolbar` | Action bar for contextual operations | `packages/core/src/Toolbar/Toolbar.doc.mjs` |
| `Carousel` | Horizontally scrollable content groups | `packages/core/src/Carousel/Carousel.doc.mjs` |
| `OverflowList` | Collapsible item list with "more" indicator | `packages/core/src/OverflowList/OverflowList.doc.mjs` |

## Form Controls

Astryx provides a complete set of accessible form inputs with consistent validation states and theme integration.

### Input Types and Selection Controls

- **`TextInput`**, **`NumberInput`**, **`DateInput`**, **`TimeInput`** — Text-based data entry with native type support
- **`Select`** — Single and multi-selection dropdowns with search capability
- **`Checkbox`**, **`Radio`**, **`Switch`** — Boolean and mutually-exclusive selection controls
- **`Slider`** — Range value selection with labeled steps

DateInput documentation: `packages/core/src/DateInput/DateInput.doc.mjs`

All form components expose `isInvalid`, `isDisabled`, and `isRequired` props following WAI-ARIA patterns, with error messages handled through a companion `Field` wrapper.

## Data Display Components

Rich data visualization and feedback primitives for dashboard and list interfaces.

### Table with Advanced Features

The **Table** component is one of Astryx's most comprehensive data display primitives, supported by a family of specialized hooks:

```tsx
import {
  Table,
  useTableSorting,
  useTablePagination,
  useTableSelection,
} from '@astryxdesign/core';

export function UsersTable({ data }) {
  const sorting = useTableSorting();
  const pagination = useTablePagination({ pageSize: 10 });
  const selection = useTableSelection();

  return (
    <Table
      columns={[
        { key: 'name', header: 'Name', sortable: true },
        { key: 'email', header: 'Email' },
        { key: 'role', header: 'Role', sortable: true },
      ]}
      rows={data}
      sorting={sorting}
      pagination={pagination}
      selection={selection}
    />
  );
}

```

Table hook sources:
- `packages/core/src/Table/useTableSelection.doc.mjs`
- `packages/core/src/Table/useTableColumnSettings.doc.mjs` (sorting)
- `packages/core/src/Table/useTablePagination.doc.mjs`

### Feedback and Status Indicators

- **`Toast`** — Non-disruptive notification system with auto-dismiss
- **`Tooltip`** — Contextual help on hover/focus
- **`Banner`** — Persistent page-level alerts
- **`EmptyState`** — Placeholder for zero-data scenarios
- **`Thumbnail`** — Image previews with loading states

Toast implementation: `packages/core/src/Toast/Toast.doc.mjs`

## Navigation & Menus

Wayfinding components for complex application hierarchies.

### Menu Systems and Controls

```tsx
import { useToast } from '@astryxdesign/core';

export function DeleteButton() {
  const toast = useToast();

  const handleDelete = async () => {
    // …perform delete
    toast.success('Item deleted successfully');
  };

  return <Button onClick={handleDelete}>Delete</Button>;
}

```

- **`Breadcrumbs`** — Hierarchical path navigation (`packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs`)
- **`DropdownMenu`** — Action menus with keyboard navigation (`packages/core/src/DropdownMenu/DropdownMenu.doc.mjs`)
- **`Menu`** and **`ContextMenu`** — Selection and right-click menus
- **`Tabs`** and **`SegmentedControl`** — View switchers with active state management
- **`Collapsible`** and **`Accordion`** — Expandable content sections

## Utility Hooks

Behavioral primitives that power component functionality and extend Astryx's capabilities into custom implementations.

### Theme, Localization, and Interaction Hooks

| Hook | Purpose | Source |
|------|---------|--------|
| `useTheme` | Access theme tokens and color schemes | `packages/core/src/theme/useTheme.doc.mjs` |
| `useTranslator` | i18n string lookup with interpolation | `packages/core/src/i18n/useTranslator.doc.mjs` |
| `useTooltip` | Programmatic tooltip control | `packages/core/src/Tooltip/useTooltip.doc.mjs` |
| `useToast` | Global toast notification dispatch | `packages/core/src/Toast/useToast.doc.mjs` |
| `useLayer` | Z-index and stacking context management | `packages/core/src/Layer/useLayer.doc.mjs` |
| `useScrollSpy` | Active section tracking on scroll | `packages/core/src/ScrollSpy/useScrollSpy.doc.mjs` |
| `useOutlineFromDOM` | Automatic focus outline detection | `packages/core/src/Outline/useOutlineFromDOM.doc.mjs` |

These hooks follow the same documentation pattern as visual components, with `*.doc.mjs` files describing parameters, return values, and usage patterns.

## Architecture and Key Files

The Astryx core package structure enforces consistency through convention-based organization:

- **`packages/core/src/**/ComponentName.doc.mjs`** — Prop definitions, JSDoc documentation, and usage examples for every component
- **`packages/core/src/theme/*`** — Design tokens, color schemes, and `ThemeProvider` implementation
- **`packages/core/src/i18n/*`** — `InternationalizationProvider` and locale loading utilities
- **[`packages/core/babel.config.json`](https://github.com/facebook/astryx/blob/main/packages/core/babel.config.json)** — Babel transformation config for StyleX compilation
- **[`packages/core/esbuild-plugin-babel.d.ts`](https://github.com/facebook/astryx/blob/main/packages/core/esbuild-plugin-babel.d.ts)** — Type definitions for the build pipeline integration

According to the Facebook Astryx source code, all components share a **common styling foundation** through StyleX, with CSS-in-JS utilities that compile to static class names at build time for optimal runtime performance.

## Summary

- **Astryx core components** live in `packages/core` and export 30+ UI primitives grouped into six functional families
- **Basic UI primitives** (`Button`, `Badge`, `Avatar`) provide foundational visual elements with theme-aware styling
- **Layout containers** (`Card`, `Dialog`, `SideNav`) handle structure, layering, and responsive organization
- **Form controls** offer complete input coverage with consistent accessibility and validation patterns
- **Data display** components include the feature-rich `Table` with pagination, sorting, and selection hooks
- **Navigation primitives** support complex wayfinding with keyboard-accessible menu systems
- **Utility hooks** (`useTheme`, `useToast`, `useTableSorting`) extend functionality to custom implementations

## Frequently Asked Questions

### What package manager command installs Astryx core components?

Install via `npm install @astryxdesign/core` or `yarn add @astryxdesign/core`. The core package includes all UI primitives and hooks; individual components are tree-shakeable for optimal bundle size. Refer to [`packages/core/README.md`](https://github.com/facebook/astryx/blob/main/packages/core/README.md) for framework-specific integration notes.

### How does Astryx handle component theming?

Astryx uses **StyleX** for compile-time CSS generation with theme tokens defined in `packages/core/src/theme/*`. The `useTheme` hook provides runtime access to color schemes, spacing scales, and typography values. Theme changes propagate through a React context provider with zero CSS-in-JS runtime overhead.

### Can Astryx components be used outside React applications?

While Astryx components are implemented in React, the **prop-driven API conventions** and **TypeScript definitions** are designed to be framework-agnostic in structure. The styling system outputs standard CSS class names that could theoretically power non-React implementations, though the primary distribution targets React, Next.js, and modern UI stacks.

### Where is the documentation for a specific Astryx component?

Every component ships with a companion `*.doc.mjs` file in its source folder (e.g., `packages/core/src/Button/Button.doc.mjs`). These files contain JSDoc-based prop definitions, usage examples, and design guidelines. The repository's documentation site consumes these files to generate interactive component pages.