Pre-alphaThe registry and the CLI are not published yet.Roadmap

Components overview

What an Axiom component is, and how primitives, compositions and blocks fit together.

A component is a piece of UI you can see: a button, a search bar, a settings row, an app bar. It renders something and exposes an API to control it. Like everything in Axiom, it is copied into your project, so the file is yours once it’s there.

Components come in three kinds, from the most generic to the most concrete:

Foundations → Primitives → Compositions → Blocks
Primitives
Icon, Switch, ItemAtoms · Molecules · Organisms · Templates
Composition
Settings ItemOne ready-made row, installed with its primitives
Block
Settings SectionA titled group of Settings Items
KindWhat it isExamples
PrimitivesGeneric building blocks with an API meant to be reused in many screensButton, Text, Icon, Input, Item, Card, AppBar, Tabs
CompositionsConcrete interfaces assembled from primitives, ready to useProduct Card, Settings Item
BlocksComplete or near-complete sections of an appSettings Section, onboarding, paywall

Each kind is built from the ones before it. A primitive uses foundations (tokens, typography, the theme) and the headless core. A composition uses primitives. A block uses primitives and compositions.

Primitives

A primitive doesn’t know what your app is about. Card is a surface with a header, media and a footer; it has no idea whether it will hold a product, a trip or a post. Item is a row with a leading slot, a title and a trailing slot; it can be a message, a contact or a setting.

That generality is the point: one primitive covers many screens, and its props describe layout and states, not content. Primitives are sorted with Atomic Design, see below.

Native props pass through

A primitive, and each of its parts, accepts the props of the element it renders at its root: View props for a Card.Header, Pressable props for a Chip with onPress, ScrollView props for a Scaffold.Content. They land on that element, so testID, onLayout, hitSlop, accessibility props or contentContainerStyle work without copying the component.

<Chip.Group testID="filters" onLayout={onLayout} style={{ paddingVertical: 8 }}>
	{chips}
</Chip.Group>

A few props stay under the component’s control because its behavior depends on them, such as the accessibility role of a tab. Handlers the component also needs, like onLayout, are called after its own. Compositions don’t follow this rule: their API is fixed, and you change the file instead.

Compositions

A composition is a primitive, or a few of them, put to one concrete use. Product Card is a Card with a product image, a name, a price, a badge and an add-to-cart button. Settings Item is an Item with an icon, a label, a value and a chevron or a switch.

Compositions are distributed code, not documentation snippets. Each one has its own page with a preview, and you install it like any other component:

npx axiom add settings-item
pnpm dlx axiom add settings-item
yarn dlx axiom add settings-item
bun x axiom add settings-item

The CLI copies the composition and the primitives it uses. From there you change the file like anything else you own. Browse them in the composition catalog.

Example or composition?

Primitive pages also show code: “Navigation row”, “Summary widget on a dashboard”. Those are examples. They are not the same thing as compositions.

ExampleComposition
PurposeShows how to use a primitive’s APIGives you a finished interface to reuse
Where it livesIn the primitive’s page, as a snippetIn the registry, with its own page
How you get itRead it, copy the lines you neednpx axiom add <name>
Has its own APINo, it’s a use of the primitive’s propsYes: typed props, documented in a table

When a pattern keeps coming back across apps and deserves its own props, it becomes a composition. Until then, it stays an example.

Blocks

A block is a section of an app, or a whole screen: a settings group, a paywall, a sign-in form. It is built from primitives and compositions, uses realistic content and is meant to be adapted to your product.

How the kinds connect

The same primitive can lead to many compositions, and a composition can end up in several blocks. Two chains show the idea:

Card  →  Product Card   →  product grid (Commerce)
Item  →  Settings Item  →  Settings Section

Each primitive page lists the compositions built with it, and each composition page links back to its primitives and forward to the blocks that use it.

How primitives are organized

Axiom has a lot of primitives, and they don’t all work at the same scale. A button is used on its own. A search bar is built from an input and a button. A scaffold arranges a whole screen. To keep them easy to find, primitives are sorted into levels borrowed from Atomic Design: atoms, molecules, organisms and templates. These levels only organize primitives. They are not the public hierarchy, which stays primitives, compositions and blocks.

Atomic Design

Atomic Design is a methodology described by Brad Frost in Atomic Design. It borrows its vocabulary from chemistry: atoms combine into molecules, and molecules combine into larger organisms. Applied to interfaces, it describes five stages.

StageIn Brad Frost’s wordsHis example
AtomsBasic building blocks that can’t be broken down further without ceasing to be functionalA label, an input, a button
MoleculesRelatively simple groups of UI elements functioning together as a unitA search form: label, input and button
OrganismsRelatively complex components composed of groups of molecules and/or atomsA header with a logo, navigation and a search form
TemplatesPage-level objects that place components into a layout and show the content structureA page skeleton with placeholder content
PagesSpecific instances of templates with real, representative contentThe home page with real text and images

Two points from the book matter for how Axiom uses it:

  • It isn’t a linear process. You don’t design every atom before building a screen. It’s a mental model that lets you move between the abstract pieces and the concrete interface they produce.
  • It isn’t rigid dogma. The names are a tool. Teams are encouraged to adapt the levels and the vocabulary to what they build.

How Axiom applies it

Axiom keeps the first four stages to sort its primitives:

LevelIn AxiomExamples
AtomsThe smallest units you use directly in a screen, each installed on its ownButton, Input, Avatar, BottomSheet
MoleculesA few atoms forming one coherent functionSearchBar, DatePicker, Attachment
OrganismsComponents that own a full interaction, with their own layout, states and input handlingPasscode
TemplatesStructures that frame a screen or a large area of itScaffold, AppBar, BottomTabBar

The differences with the book are deliberate:

  • There are no pages. A page, in Atomic Design, is a template filled with real content. A registry can’t ship your content. The concrete end of Axiom is covered by compositions and blocks, which use realistic content that you rewrite for your app.
  • An atom is the smallest piece you can use on its own. A BottomSheet or a Dialog is more than a single HTML-like element, but in a mobile app you place it directly and nothing smaller is useful by itself. The pieces below that level have no look of their own and live in the headless core: Slot, Portal, Overlay, Tappable.
  • Atomic Design only covers what you see. Interaction logic that several components share, such as pull-to-refresh or long press, lives in behaviors. Recurring UX problems that combine components and behaviors, such as a search flow or loading states, live in patterns. They are a separate axis, not a level of the component hierarchy.

When a primitive doesn’t fit a level cleanly, it goes where its responsibility is best described. The levels are a guide, not a rule to argue about.

Why this structure

A shared vocabulary. “Composition” or “block” tells you how concrete a component is before you open it. “Molecule” or “template” tells you the scale of a primitive. Contributors and users look in the same place for the same thing.

Composition over configuration. When a new need appears, the first answer is to combine existing primitives into a composition rather than add props to a large primitive. Card doesn’t get a price prop; Product Card exists instead.

One-way dependencies. Blocks import compositions and primitives, compositions import primitives, never the reverse. A primitive doesn’t know about the compositions that use it, so you can change or remove a composition without breaking a primitive.

Progressive adoption. Because dependencies only go down, npx axiom add settings-section copies the block, the Settings Item composition and the primitives they need, and nothing else. You can start with one primitive and add more concrete pieces as your app grows.