---
title: "Components"
description: "Every React and Next.js component in Systhema, how to install and import them, and how your tokens decide their variants."
requested_language: ar
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/ar/next/components
version: unreleased (main)
docs_index: https://docs.systhema.app/ar/next/llms.txt
---
> This page isn't translated yet. Showing English.


Systhema's components are React components styled by the CSS that `@systhemaui/core` generates from your design tokens. `@systhemaui/react` works in any React app; `@systhemaui/next` re-exports it and swaps in Next.js versions where `next/link`, `next/image` or `next/navigation` help. Every page in this section shows the component live, rendered with the default tokens.

```tsx preview title="Components with the default tokens"
import { Button, Card, Chip, Heading, Paragraph, Stack } from '@systhemaui/next'

export default function Demo() {
  return (
    <Card style={{ maxWidth: 480 }}>
      <Stack gap="xs">
        <Chip>New</Chip>
        <Chip>Components</Chip>
      </Stack>
      <Heading.h3>Build from tokens</Heading.h3>
      <Paragraph>Change a color or a radius in Figma, sync, and every component follows.</Paragraph>
      <Stack gap="sm">
        <Button.a href="#gallery" variant="primary">
          Browse
        </Button.a>
        <Button.a href="#token-driven-variants" variant="secondary">
          About variants
        </Button.a>
      </Stack>
    </Card>
  )
}
```

## Installation

In a Next.js app, install `@systhemaui/next` with core:

```bash
pnpm add @systhemaui/core @systhemaui/next
```

In a React app without Next.js, install `@systhemaui/react` instead:

```bash
pnpm add @systhemaui/core @systhemaui/react
```

The packages come from the private GitHub Packages registry; see [Registry access](https://docs.systhema.app/ar/next/getting-started/registry-access.md). The components also need the Tailwind CSS plugin and `packages.react` in `systhema.config.ts`, so their classes are generated; see [Installation](https://docs.systhema.app/ar/next/getting-started/installation.md) and [Next.js](https://docs.systhema.app/ar/next/nextjs.md).

## Importing components

Every page in this section imports from `@systhemaui/next`, as a Next.js project would:

```tsx
import { Button, Heading, Section } from '@systhemaui/next'
```

In a React app, import the same names from `@systhemaui/react`. Where `@systhemaui/next` ships its own implementation, the component page has a "Next.js" section that says what changes. A few low-level helpers exist in `@systhemaui/react` only; [Utilities](https://docs.systhema.app/ar/next/components/utilities.md) lists them.

Most components are server-safe and render in a Server Component. The interactive ones (`Accordion`, `Gallery`, `Carousel`, `Header`, the listeners, the cookie banner) are client components that you render from a Server Component as they are.

## Gallery

### Provider

| Component                         | What it is                                                                        |
| --------------------------------- | --------------------------------------------------------------------------------- |
| [SysthemaProvider](https://docs.systhema.app/ar/next/components/provider.md) | The root provider: config forwarding, the scroll listeners and the cookie banner. |

### Layout

| Component                   | What it is                                                                      |
| --------------------------- | ------------------------------------------------------------------------------- |
| [Article](https://docs.systhema.app/ar/next/components/article.md)     | A page-level article wrapper with theme, background and article padding.        |
| [Section](https://docs.systhema.app/ar/next/components/section.md)     | A themed band with section padding around the container.                        |
| [Columns](https://docs.systhema.app/ar/next/components/columns.md)     | Responsive column layouts with alignment, dividers, sticky columns and stagger. |
| [Stack](https://docs.systhema.app/ar/next/components/stack.md)         | Flex rows and columns with token gaps, dividers and mobile overrides.           |
| [Feature](https://docs.systhema.app/ar/next/components/feature.md)     | A media-and-content band, reversible, with `FeatureMedia` and `FeatureContent`. |
| [Figure](https://docs.systhema.app/ar/next/components/figure.md)       | Figures that break out to the container, the screen or the card edges.          |
| [Separator](https://docs.systhema.app/ar/next/components/separator.md) | A themed horizontal rule.                                                       |

### Page chrome

| Component             | What it is                                                                             |
| --------------------- | -------------------------------------------------------------------------------------- |
| [Header](https://docs.systhema.app/ar/next/components/header.md) | A static, sticky or fixed header with navigation, sub-navigation and a mobile menu.    |
| [Footer](https://docs.systhema.app/ar/next/components/footer.md) | Simple and advanced footers with navigation groups, social links and a copyright line. |
| [Hero](https://docs.systhema.app/ar/next/components/hero.md)     | `HeroSimple`, `HeroBackground` and `HeroFeature` page openers.                         |

### Typography

| Component                   | What it is                                                              |
| --------------------------- | ----------------------------------------------------------------------- |
| [Heading](https://docs.systhema.app/ar/next/components/heading.md)     | `Heading.h1` to `Heading.h6` in the token text styles.                  |
| [Paragraph](https://docs.systhema.app/ar/next/components/paragraph.md) | Body, lead, small and label paragraphs.                                 |
| [Link](https://docs.systhema.app/ar/next/components/link.md)           | Text links with same-page hash scrolling and new-tab cues.              |
| [List](https://docs.systhema.app/ar/next/components/list.md)           | Bullet, number and check lists, and `CustomList` with your own markers. |
| [Quote](https://docs.systhema.app/ar/next/components/quote.md)         | Blockquotes with icon, citation, avatar and labels.                     |

### Actions

| Component             | What it is                                                                 |
| --------------------- | -------------------------------------------------------------------------- |
| [Button](https://docs.systhema.app/ar/next/components/button.md) | Token-variant buttons as a button, link or div, with title and icon parts. |
| [Chip](https://docs.systhema.app/ar/next/components/chip.md)     | Small labels, tags and filter chips.                                       |
| [Icon](https://docs.systhema.app/ar/next/components/icon.md)     | Decorative and linked icons, with an optional background.                  |

### Media

| Component                          | What it is                                                       |
| ---------------------------------- | ---------------------------------------------------------------- |
| [Image](https://docs.systhema.app/ar/next/components/image.md)                | Images cropped to an aspect ratio, with object fit and parallax. |
| [Video](https://docs.systhema.app/ar/next/components/video.md)                | Videos with deferred controls, preload and parallax.             |
| [MediaWrapper](https://docs.systhema.app/ar/next/components/media-wrapper.md) | A play affordance and overlays around an image or video.         |
| [Avatar](https://docs.systhema.app/ar/next/components/avatar.md)              | Round profile images.                                            |
| [Gallery](https://docs.systhema.app/ar/next/components/gallery.md)            | A Swiper gallery with navigation and a slide counter.            |
| [Carousel](https://docs.systhema.app/ar/next/components/carousel.md)          | A carousel with pagination, navigation and thumbnails.           |

### Content

| Component                   | What it is                                               |
| --------------------------- | -------------------------------------------------------- |
| [Card](https://docs.systhema.app/ar/next/components/card.md)           | Token-variant cards as a container or a whole-card link. |
| [Accordion](https://docs.systhema.app/ar/next/components/accordion.md) | Disclosure panels with an animated open state.           |

### Forms

| Component                                 | What it is                                                            |
| ----------------------------------------- | --------------------------------------------------------------------- |
| [Form](https://docs.systhema.app/ar/next/components/form.md)                         | The form wrapper and the `FormRow` and `FormGroup` layout.            |
| [Form controls](https://docs.systhema.app/ar/next/components/form-controls.md)       | Label, input, textarea, file input, description and error primitives. |
| [Select](https://docs.systhema.app/ar/next/components/form-select.md)                | A native select with a placeholder and a token icon.                  |
| [Radios and checkboxes](https://docs.systhema.app/ar/next/components/form-choice.md) | Single radio and checkbox controls.                                   |
| [Form fields](https://docs.systhema.app/ar/next/components/form-fields.md)           | Eleven labelled fields with descriptions, errors and widths.          |
| [SearchField](https://docs.systhema.app/ar/next/components/search-field.md)          | A search input with a trailing magnifier.                             |

### Posts

| Component                                          | What it is                                                    |
| -------------------------------------------------- | ------------------------------------------------------------- |
| [PostsList](https://docs.systhema.app/ar/next/components/posts-list.md)                       | The posts listing in grid, row and lead layouts, with paging. |
| [PostCard and HighlightCard](https://docs.systhema.app/ar/next/components/post-card.md)       | Listing cards and highlight cards.                            |
| [PostMeta](https://docs.systhema.app/ar/next/components/post-meta.md)                         | The author and date byline.                                   |
| [ShareButtons](https://docs.systhema.app/ar/next/components/share-buttons.md)                 | Share links as pills, a floating sidebar or a sticky bar.     |
| [ArchiveSearchFilter](https://docs.systhema.app/ar/next/components/archive-search-filter.md)  | Search and category or tag filters for archives.              |
| [Posts view model and helpers](https://docs.systhema.app/ar/next/components/posts-helpers.md) | `PostView`, part resolution and the listing helpers.          |

### Behaviour

| Component                                         | What it is                                         |
| ------------------------------------------------- | -------------------------------------------------- |
| [Listeners](https://docs.systhema.app/ar/next/components/listeners.md)                       | Scroll reveals, parallax and scroll-state classes. |
| [CookieConsentBanner](https://docs.systhema.app/ar/next/components/cookie-consent-banner.md) | The cookie consent banner and preferences modal.   |

### Utilities

| Component                   | What it is                                                                  |
| --------------------------- | --------------------------------------------------------------------------- |
| [Utilities](https://docs.systhema.app/ar/next/components/utilities.md) | `cn`, `LinkHelper`, `getReactConfig`, `withTagProxy` and the other helpers. |

## Token-driven variants

Props such as `variant`, `theme` and `layoutBackground` take values from your project's tokens, not from a fixed list in the code. The token export names the variants (for example the keys under `button` in the `responsiveSizing` and `colorSystem` collections), and `systhema-core sync` turns each one into three things:

1. a CSS class, `<component>-<variant>` (`button-primary`, `card-highlighted`), whose rules read that variant's token variables;
2. a member of the matching TypeScript union in the [generated types](https://docs.systhema.app/ar/next/reference/generated-types.md) (`ButtonVariant`, `CardVariant`), so an unknown variant is a type error;
3. an entry in the client token snapshot, which the component reads at render time to pick the class.

So adding a `tertiary` button in Figma and syncing gives you `variant="tertiary"`, typed and styled, without touching component code. Omitting `variant` picks the first variant in the tokens. `theme` works the same way with the color-system modes: it sets `data-theme`, and the token variables of that mode apply inside the element.

With the default Systhema tokens, the unions are:

| Type               | Values                                             | Used by                                                  |
| ------------------ | -------------------------------------------------- | -------------------------------------------------------- |
| `ColorSystem`      | `default`, `dark`                                  | `theme` on sections, cards, heroes and more              |
| `LayoutBackground` | `main`, `alternative`                              | `layoutBackground` on sections and bands                 |
| `ButtonVariant`    | `primary`, `secondary`                             | [Button](https://docs.systhema.app/ar/next/components/button.md)                                    |
| `CardVariant`      | `default`, `highlighted`                           | [Card](https://docs.systhema.app/ar/next/components/card.md)                                        |
| `AccordionVariant` | `default`                                          | [Accordion](https://docs.systhema.app/ar/next/components/accordion.md)                              |
| `GapSize`          | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl` | `gap` on [Stack](https://docs.systhema.app/ar/next/components/stack.md) and [Columns](https://docs.systhema.app/ar/next/components/columns.md) |

```tsx preview title="Variants side by side"
import { Button, Card, Column, Columns, Heading, Paragraph, Stack } from '@systhemaui/next'

export default function Demo() {
  return (
    <Stack direction="col" gap="md" style={{ width: '100%' }}>
      <Stack gap="sm">
        <Button.button variant="primary">primary</Button.button>
        <Button.button variant="secondary">secondary</Button.button>
      </Stack>
      <Columns columns={2} gap="md">
        <Column>
          <Card variant="default">
            <Heading.h5>default</Heading.h5>
            <Paragraph type="small">CardVariant</Paragraph>
          </Card>
        </Column>
        <Column>
          <Card variant="highlighted">
            <Heading.h5>highlighted</Heading.h5>
            <Paragraph type="small">CardVariant</Paragraph>
          </Card>
        </Column>
      </Columns>
    </Stack>
  )
}
```

See [Design tokens](https://docs.systhema.app/ar/next/concepts/design-tokens.md) for how tokens flow from Figma to CSS, and [Themes and backgrounds](https://docs.systhema.app/ar/next/concepts/themes.md) for how `theme` and `layoutBackground` nest.

## Accessibility

The components are held to WCAG 2.2 for semantics, ARIA, keyboard use, forms, media and motion; contrast and target sizes depend on your tokens. Each page has an "Accessibility" section, and [Accessibility](https://docs.systhema.app/ar/next/concepts/accessibility.md) sums up what the system guarantees.

## Related

- [Next.js integration](https://docs.systhema.app/ar/next/nextjs.md)
- [Styling](https://docs.systhema.app/ar/next/styling/tailwind.md)
- [Payload blocks](https://docs.systhema.app/ar/next/payload/blocks.md), which render these components