# How to Use Astryx Page Templates for Common Layout Patterns

> Learn how to use Astryx page templates to quickly scaffold common layouts like dashboards, tables, forms, and login screens, saving you development time.

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

---

**Astryx ships ready-to-use page templates located in `packages/cli/templates/pages/` that you scaffold via the CLI using `npx astryx template <name>` to instantly generate complete dashboard, table, form, and login screen layouts.**

The **facebook/astryx** repository provides a comprehensive template system that accelerates UI development by delivering pre-built, accessible page layouts. These templates handle common patterns like searchable data tables and administrative dashboards, allowing you to focus on business logic rather than boilerplate layout code.

## Understanding the Template Architecture

The Astryx template system consists of five interconnected components that transform static files into production-ready pages.

### CLI Command Handler

The **Astryx CLI** parses template commands in `packages/cli/src/commands/template.mjs`. This module discovers available templates by walking the `packages/cli/templates/pages/` directory tree, resolves user-selected templates by name, and executes the scaffolding process.

### Template Registry

The CLI automatically discovers every template by reading folder names under `packages/cli/templates/pages/`. Each folder contains a [`page.tsx`](https://github.com/facebook/astryx/blob/main/page.tsx) file that exports a default React component implementing a complete layout composition using Astryx core primitives.

### Page Template Files

Individual templates are pure React components written with Astryx core components like `Layout`, `VStack`, `Table`, and `PowerSearch`. For example, [`packages/cli/templates/pages/dashboard/page.tsx`](https://github.com/facebook/astryx/blob/main/packages/cli/templates/pages/dashboard/page.tsx) provides a complete dashboard implementation with header actions, sidebar navigation patterns, and responsive content areas.

### Theme System Integration

Templates assume a global theme is present (typically `@astryxdesign/theme-neutral`). The CLI does not embed CSS during scaffolding; you must add the theme import globally as documented in the Getting Started guide. This separation allows the same template to render with different design tokens simply by swapping the theme import.

### Post-Scaffolding Customization

After the CLI copies a template to your project (e.g., [`src/app/dashboard/page.tsx`](https://github.com/facebook/astryx/blob/main/src/app/dashboard/page.tsx)), the file becomes standard React code in your repository. You retain full ownership to edit data sources, modify component composition, or integrate with your routing system.

## Listing Available Templates

Discover all built-in layout patterns before scaffolding. The CLI reads the `packages/cli/templates/pages/` directory and returns human-readable names.

```bash
npx astryx template --list

```

This outputs template identifiers such as `dashboard`, `settings`, `table-page`, and `login-card`. Each name corresponds to a subdirectory containing the implementation files.

## Scaffolding a Page Template

Generate a complete page by specifying the template name and output directory. The CLI copies the source [`page.tsx`](https://github.com/facebook/astryx/blob/main/page.tsx), rewrites relative imports to resolve against `@astryxdesign/core`, and places the file in your target location.

```bash

# Scaffold dashboard layout into src/app/dashboard/

npx astryx template dashboard --output src/app/dashboard

```

The generated file imports Astryx primitives and renders a fully-functional layout immediately:

```tsx
// src/app/dashboard/page.tsx (generated)
import {
  Layout, LayoutHeader, LayoutContent,
  VStack, HStack, Text, Heading,
  IconButton, Icon, Button,
} from '@astryxdesign/core';
import {PowerSearch} from '@astryxdesign/core/PowerSearch';
import {Table} from '@astryxdesign/core/Table';

export default function DashboardPage() {
  return (
    <Layout>
      <LayoutHeader hasDivider>
        <HStack gap={2} vAlign="center">
          <Heading level={1}>Dashboard</Heading>
          <IconButton label="Settings" icon={<Icon name="settings" />} />
        </HStack>
      </LayoutHeader>
      <LayoutContent>
        <VStack gap={4}>
          <PowerSearch />
          <Table />
        </VStack>
      </LayoutContent>
    </Layout>
  );
}

```

## Connecting Real Data Sources

Scaffolded templates include placeholder data (such as static arrays in `table-page`). Replace these with dynamic data fetching using standard React patterns while preserving the template's layout structure.

```tsx
import {useEffect, useState} from 'react';
import TablePageTemplate from '@/templates/table-page/page';
import type {DogRow} from '@/types';

export default function DogTable() {
  const [dogs, setDogs] = useState<DogRow[]>([]);

  useEffect(() => {
    fetch('/api/dogs')
      .then(r => r.json())
      .then(setDogs);
  }, []);

  // Pass fetched data to the template's expected props
  return <TablePageTemplate data={dogs} />;
}

```

## Customizing Layout Components

Since templates export standard React components, you can modify any aspect of the layout. Common customizations include replacing header actions, adjusting stack layouts, or swapping content blocks.

```tsx
// src/app/dashboard/custom-header.tsx
import {LayoutHeader, HStack, IconButton, Button, Heading} from '@astryxdesign/core';
import {BellIcon, UserIcon} from '@heroicons/react/24/outline';

export default function CustomDashboardHeader() {
  return (
    <LayoutHeader hasDivider>
      <HStack gap={2} vAlign="center">
        <Heading level={1}>My App Dashboard</Heading>
        <IconButton label="Notifications" icon={<BellIcon />} variant="ghost" />
        <IconButton label="Profile" icon={<UserIcon />} variant="ghost" />
        <Button label="Create New" onClick={() => console.log('create')} />
      </HStack>
    </LayoutHeader>
  );
}

```

Replace the default header in your scaffolded page by importing `CustomDashboardHeader` and substituting it for the generated `LayoutHeader` component.

## Applying Alternative Themes

Change the visual appearance without modifying template code by switching global theme imports. The templates reference design tokens (colors, spacing, typography) that resolve at runtime based on your global CSS imports.

```css
/* globals.css */
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-y2k/theme.css';

```

The scaffolded page automatically inherits the new theme's visual properties, including dark mode variants and brand-specific color palettes.

## Summary

- **Astryx page templates** reside in `packages/cli/templates/pages/` and provide complete layout implementations for dashboards, tables, forms, and authentication screens.
- Use `npx astryx template --list` to discover available patterns and `npx astryx template <name> --output <path>` to scaffold them into your project.
- The CLI copies files from `packages/cli/src/commands/template.mjs` and rewrites imports to resolve against `@astryxdesign/core` automatically.
- Templates are pure React components using `Layout`, `VStack`, `HStack`, `Table`, and `PowerSearch` primitives that you can customize after scaffolding.
- Connect real data by replacing placeholder arrays with `useEffect` hooks or data fetching libraries while maintaining the template's layout structure.
- Apply different visual themes by changing global CSS imports; templates automatically adapt to new design tokens without code changes.

## Frequently Asked Questions

### How do I list all available Astryx page templates?

Run `npx astryx template --list` in your terminal. The CLI walks the `packages/cli/templates/pages/` directory and displays each folder name (such as `dashboard`, `table-page`, or `login-card`) that contains a scaffoldable [`page.tsx`](https://github.com/facebook/astryx/blob/main/page.tsx) file.

### Can I use Astryx page templates without the CLI?

Yes, but you must manually copy files from `packages/cli/templates/pages/` into your project and manually resolve import paths. The CLI automates the import rewriting that maps template-relative paths to `@astryxdesign/core`, so manual setup requires ensuring your module resolution matches the template's import statements.

### Where do I add my data fetching logic in a scaffolded template?

Add data fetching logic directly in the generated [`page.tsx`](https://github.com/facebook/astryx/blob/main/page.tsx) file after scaffolding. Replace the placeholder data arrays (like the static "Dogs" array in `table-page`) with React state and `useEffect` hooks, or convert the component to accept props from a parent data loader. The template remains a standard React component that accepts props and renders children.

### Do Astryx page templates include styling and themes?

Templates include component structure and layout logic but do not embed CSS. They assume you have imported a global theme (such as `@astryxdesign/theme-neutral`) in your application's entry point. The components use Astryx design tokens that resolve based on your active theme, allowing the same template to render with different visual styles by changing the CSS import.