---
title: Using components
description: A tour of the catalog, and how to choose.
---

Reed renders MDX through a fixed catalog of 37 components. They are available in every
page with no import. Full props for each are in
[the component reference](/docs/reference/components/callouts); this page is about
choosing.

## The shape of the catalog

| Family | Components |
|---|---|
| Callouts | `Callout` plus 9 fixed-intent shorthands |
| Layout and surfaces | `Card`, `CardGroup`, `Columns`, `Tiles`, `Frame`, `Panel`, `Aside`, `Banner`, `Accordion`, `AccordionGroup` |
| Procedural | `Steps`, `Step`, `Tabs`, `Tab`, `CodeBlock`, `CodeGroup` |
| API reference | `ParamField`, `ResponseField`, `Badge`, `Table` |
| File trees | `Files`, `Folder`, `File` |
| Other | `Expandable`, `Icon`, `Tooltip`, `Update` |

## Fixed catalog, checked at build time

There is no arbitrary import surface. A component outside the catalog is a `DS-S06`
diagnostic — an error — rather than something that renders as literal text on a published
page.

Several components also constrain their children: `CardGroup` takes `Card` only, `Steps`
needs at least two `Step`s, `Tabs` at least two `Tab`s. A stray paragraph between cards
fails the check instead of producing a broken grid.

That strictness is the point. The failure happens at `reed check`, in a second, offline —
not in a screenshot someone sends you a week later.

## Prefer plain markdown

Most documentation is prose, headings, lists, links and fenced code blocks. Those need no
components, and a page built from them is easier to read in the source, in a diff, and in
the markdown mirror.

Reach for a component when it does something markdown cannot:

- **`Steps`** — a sequence where the numbering carries meaning
- **`Tabs`** — genuine alternatives, where the reader picks one and ignores the rest
- **`CodeGroup`** — one thing shown in several languages
- **`ParamField`** — a parameter with a type, a default and a required flag
- **Callouts** — something that would be missed if it were a sentence

## Do not over-decorate

Reed warns when a page carries more than 40 component elements, when callouts pile up
adjacent to each other, and when accordions run together without a group. These are
`DS-D*` warnings — they do not fail a build — but they are usually right. A page where
every paragraph is a card has no emphasis left to spend.

## The fenced-code trap

MDX parses a fenced code block inside a JSX element differently from one at the top level.
Keep fences at the top level of the page until you have a specific reason not to — see
[MDX pitfalls](/docs/authoring/mdx-pitfalls).