# How to Use the Core Astryx Package for Basic Components

> Learn to use the core Astryx package for basic components. Build type-safe React UI elements like buttons and cards with automatic theming via StyleX.

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

---

**The @astryxdesign/core package provides type-safe React components that automatically inherit the active theme through StyleX, exposing a consistent prop API for buttons, cards, layouts, and other fundamental UI building blocks.**

The **facebook/astryx** repository structures its component library around the core package, which serves as the foundation for building consistent internal tools. When you use the core Astryx package for basic components, you gain access to a unified theming system based on CSS custom properties, accessibility-first prop patterns, and zero-config TypeScript support.

## Installation and Setup

Install the core package via your package manager of choice. The package ships with StyleX-generated CSS, so ensure your build pipeline can process StyleX styles (typically handled by the Astryx CLI or your existing StyleX configuration).

```bash
npm install @astryxdesign/core

```

## Importing Components from the Core Package

The package entry point at [`packages/core/src/index.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/index.ts) re-exports every component, enabling both barrel imports and direct path imports for tree-shaking optimization.

### Barrel Imports vs. Direct Path Imports

You can import multiple components from the root:

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

```

For better bundle size and faster build times, import directly from component paths:

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

```

Each component lives in its own folder under `packages/core/src/<Component>/` and includes a documentation module (`<Component>.doc.mjs`) that powers the CLI docs and Storybook generation.

## Component Architecture and Theming

### StyleX Token System

Components read CSS custom properties defined in [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts) and apply them via StyleX. The token registry is defined in [`packages/core/src/theme/tokens.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.ts), and the generated CSS is emitted during the build step. This ensures that when you use the core Astryx package for basic components, they automatically pick up color, spacing, and typography values from your active theme.

### BaseProps and Accessibility Patterns

All interactive components follow the `BaseProps<T>` pattern defined in [`packages/core/src/utils/mergeProps.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/utils/mergeProps.ts). This utility merges props while preserving refs and event handlers, ensuring consistent behavior across the library. Components expose ARIA-friendly props such as `label`, `isIconOnly`, and `tooltip` by default, making accessibility configurations automatic rather than opt-in.

## Working with Basic Components

### Standard Button Implementation

The Button component supports variants, states, and icons through a unified prop interface:

```tsx
// Basic primary button
import { Button } from '@astryxdesign/core/Button';

function SaveButton() {
  return (
    <Button
      label="Save changes"
      variant="primary"
      onClick={() => console.log('saved')}
    />
  );
}

```

### Icon-Only and Destructive Patterns

For actions requiring visual emphasis or icon-only presentation:

```tsx
// Icon-only button (use IconButton for pure icons)
import { Button } from '@astryxdesign/core/Button';
import { Icon } from '@astryxdesign/core/Icon';

function DeleteButton() {
  return (
    <Button
      label="Delete item"
      variant="destructive"
      isIconOnly
      icon={<Icon icon="trash" size="sm" />}
    />
  );
}

```

### Disabled States with Tooltips

Components handle disabled states and contextual tooltips through declarative props:

```tsx
// Disabled button with tooltip
import { Button } from '@astryxdesign/core/Button';

function DisabledSubmit() {
  return (
    <Button
      label="Submit"
      variant="primary"
      isDisabled
      tooltip="Complete the required fields first"
    />
  );
}

```

### Layout Components

Group related actions using the ButtonGroup component, which manages spacing and alignment automatically:

```tsx
// Using ButtonGroup to layout multiple buttons
import { Button, ButtonGroup } from '@astryxdesign/core';

function FormActions() {
  return (
    <ButtonGroup size="sm" label="Form actions">
      <Button label="Cancel" variant="secondary" onClick={() => {}} />
      <Button label="Save" variant="primary" onClick={() => {}} />
    </ButtonGroup>
  );
}

```

## Shared Utilities and Hooks

The core package includes reusable logic in `packages/core/src/hooks/` for common interactions. **useTheme** provides the current theme context to components, while **useCollapsible** and **useListFocus** manage complex keyboard navigation and display states. The **mergeProps** utility in [`packages/core/src/utils/mergeProps.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/utils/mergeProps.ts) ensures that event handlers and refs compose correctly when wrapping components.

## Development Workflow

### Documentation and Testing

Every component includes a Jest/Vitest test file (e.g., [`Button.test.tsx`](https://github.com/facebook/astryx/blob/main/Button.test.tsx)) and a documentation module consumed by the CLI. When you create new components following the established pattern in `packages/core/src/`, the system automatically generates reference pages and Storybook stories from the `.doc.mjs` files.

## Summary

- **Import directly** from `@astryxdesign/core` or use path-specific imports like `@astryxdesign/core/Button` for optimal tree-shaking.
- **Theming is automatic** through StyleX tokens defined in [`theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/theme/tokens.stylex.ts), requiring no manual CSS imports.
- **Accessibility is built-in** via the `BaseProps` pattern and ARIA-friendly prop interfaces.
- **Documentation is co-located** with source code in `.doc.mjs` files, powering both CLI and Storybook outputs.
- **Hooks and utilities** like `useTheme` and `mergeProps` are available for custom component development.

## Frequently Asked Questions

### How do I customize the theme when using the core Astryx package?

The theme system relies on CSS custom properties defined in [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts). Override these tokens at the application level or provide a custom theme configuration through the StyleX provider. Components automatically read these values through the `useTheme` hook, requiring no prop drilling or manual style overrides.

### What is the difference between Button and IconButton components?

While the standard `Button` component supports an `isIconOnly` prop for icon-only appearances, the dedicated IconButton (if exported) provides optimized sizing and accessibility defaults specifically for icon-only interactions. Check the specific component exports in [`packages/core/src/index.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/index.ts) to see which pattern your version supports.

### Where are component tests located in the core package?

Each component maintains its test suite in the same directory as its implementation. For example, Button tests reside in [`packages/core/src/Button/Button.test.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/Button/Button.test.tsx) alongside the main [`Button.tsx`](https://github.com/facebook/astryx/blob/main/Button.tsx) file and `Button.doc.mjs` documentation module.

### Can I use mergeProps for my own components outside the core package?

Yes. The `mergeProps` utility in [`packages/core/src/utils/mergeProps.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/utils/mergeProps.ts) is designed to handle complex prop merging, including event handler composition and ref forwarding. Import it directly to ensure your custom components maintain the same behavior patterns as the official Astryx components.