Components

Ardo ships the components documentation pages need most: callouts, badges, cards, tabs, accordions, steps, code blocks, icons, and landing-page blocks. Each one follows the theme in light and dark mode and works with the keyboard. The examples below run in the real layout of this site, so switch the theme in the header or resize the window to see them in context.

In MDX, use the components without imports, for example Tip, Card, and Tabs. In TSX, import their Ardo-prefixed equivalents from ardo/ui, such as ArdoTip, ArdoCard, and ArdoTabs. Landing-page components are imported explicitly in both.

Callouts

Choose the variant that matches the information. All five use the site's theme tokens and support a custom title.

<Tip title="Keep related instructions together">Put the guidance next to the task.</Tip>

The same variants are available as GitHub-style alerts in plain Markdown.

Badges

Badges add a compact status to a sentence. They stay inline: New Stable Preview Deprecated Reference ✦With icon.

<Badge variant="success">Stable</Badge>
<Badge icon="✦">With icon</Badge>

Cards

Use linked cards for navigation and static cards for a short summary. The grid collapses to one column on small screens.

<CardGroup cols={2}>
  <Card title="Getting Started" icon="Rocket" href="/guide/getting-started">
    Set up a documentation site.
  </Card>
  <Card title="Local components" icon="Code">
    Import components into your MDX routes.
  </Card>
</CardGroup>

Tabs

Use tabs for equivalent choices, such as package managers. Select a tab or focus it and use Left, Right, Home, and End to move through the choices.

pnpm add ardo

<Tabs defaultValue="pnpm">
  <TabList>
    <Tab value="pnpm">pnpm</Tab>
    <Tab value="npm">npm</Tab>
  </TabList>
  <TabPanels>
    <TabPanel value="pnpm">pnpm add ardo</TabPanel>
    <TabPanel value="npm">npm install ardo</TabPanel>
  </TabPanels>
</Tabs>

For custom components that create tabs or panels internally, set defaultValue on Tabs and give each tab/panel pair matching explicit value props.

Accordions

Put optional explanations in an accordion. In a group with onlyOneOpen, opening an item closes its sibling. Space and Enter toggle the focused item; Up and Down move between triggers.

<AccordionGroup onlyOneOpen>
  <Accordion title="Can I use React components?" icon="Code">
    Yes. Import a component into an MDX route.
  </Accordion>
  <Accordion title="Does it work without a server?" icon="Server">
    Yes. The production build contains static files.
  </Accordion>
</AccordionGroup>

A standalone accordion can start open:

Steps

Wrap an ordered list in Steps to show a sequence. Each step can contain prose, links, or code blocks.

<Steps>
  <ol>
    <li>Create a home route.</li>
    <li>Write a guide.</li>
    <li>Build the site.</li>
  </ol>
</Steps>

Code Blocks

Code blocks include a copy button that copies the code without the title or line numbers. Markdown fences are highlighted at build time; the CodeBlock component also accepts a string directly.

pnpm add ardo

<CodeBlock language="bash" title="terminal" code="pnpm add ardo" />

Use CodeGroup for related snippets with their own file names:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({ title: "My docs" })

# Welcome

Start with your first guide.

Markdown fences support titles, highlighted lines, line numbers, and wrapped agent prompts; see Syntax Highlighting.

In TSX Routes

The ArdoCodeBlock component can be used directly in .tsx route files. Just write the code as children — no template literals or special escaping needed:

import { ArdoCodeBlock } from "ardo/ui"

export default function MyPage() {
  return (
    <ArdoCodeBlock language="tsx">
      export function Hello() {
        return <div>Hello world!</div>
      }
    </ArdoCodeBlock>
  )
}

The ardo:codeblock-highlight Vite plugin processes ArdoCodeBlock before the JSX parser runs, so the children can contain any syntax (<, {, >, etc.) without causing errors. Common indentation is stripped automatically.

The code prop and template literal children are also supported:

<ArdoCodeBlock code="const x = 42" language="typescript" />

If the language prop is dynamic (from a variable), build-time highlighting is skipped and the code renders as plain text.

Icons

Ardo includes 50 Streamline Core Line icons for documentation content. They share the same 14 × 14 grid, rounded strokes, and currentColor as the built-in sidebar and header controls.

These are the registered content icons, shown at 14 and 28 pixels. Use the visible name with Icon, or import its component from ardo/icons.

• Archive
• ArrowRight
• BookOpen
• Bookmark
• Branch
• Bug
• Check
• Clock
• Cloud
• Code
• Copy
• Database
• Download
• ExternalLink
• FileCode
• FileText
• Flag
• Folder
• Globe
• Help
• History
• Image
• Info
• Languages
• Layers
• LayoutGrid
• Lightbulb
• Link
• List
• ListChecks
• Lock
• MessageCircle
• Package
• Pencil
• Plug
• Rocket
• Search
• Server
• Settings
• ShieldCheck
• Table
• Terminal
• TestTube
• TriangleAlert
• Upload
• User
• Users
• Workflow
• Wrench
• Zap

Use in MDX

All 50 Core icons are available automatically. Use their names directly without imports or a registration call:

<Icon name="Zap" size={20} />
<Card title="Deploy your site" icon="Rocket">
  Build the static output and publish it to your host.
</Card>

Use in React

import { BookOpen, Rocket, ShieldCheck } from "ardo/icons"

<BookOpen size={20} />
<Rocket size={28} className="launch-icon" />
<ShieldCheck size={20} aria-label="Security checks passed" />

The default size is 24 px. Set size to a number or CSS length, or pass native width and height attributes. Icons inherit the surrounding text color. They are decorative by default; supply aria-label or aria-labelledby when the icon conveys information without accompanying text.

ArdoIcon renders a registered icon by name, for example inside a link:

import { ArdoIcon, ArdoLink } from "ardo/ui"

export function LaunchLink() {
  return (
    <ArdoLink to="/guide/getting-started">
      <ArdoIcon name="Rocket" aria-hidden /> Get started
    </ArdoLink>
  )
}

Add or Override Icons

Use registerIcons() in app/root.tsx to add other React SVG components or brand icons:

import { Github } from "ardo/icons"
import { registerIcons } from "ardo/ui"

registerIcons({ Github })

Then use <Icon name="Github" /> in MDX. Registering an existing name overrides its built-in component. For icons from another library, declare that library as a direct dependency and import its components in your registration module.

getRegisteredIconNames() returns the built-in and custom registry keys when you need to validate user-facing configuration.

Choose an Icon

Use these names when importing from ardo/icons or referring to an icon in MDX. Each icon below is rendered at 20 px.

Content and navigation

Development and delivery

Infrastructure and security

People and communication

Guidance and discovery

Planning and maintenance

Brand Icons and License

Github, Linkedin, Npm, Twitter, and Youtube are also available from ardo/icons, with matching Icon aliases such as GithubIcon. Brand marks retain their own proportions and colors follow currentColor.

Core icons are © Streamline Design Inc., used under the Streamline Premium License for use as part of Ardo. They are not covered by Ardo's MIT license. See ICONS-LICENSE.md for redistribution terms and attribution.

Hero and Features

Hero and Features compose landing pages. This compact hero shows its secondary text and actions; on a home page, add name for the main heading and optionally an image or version badge.

Your project, clearly explained.

Guides, API reference, and live React examples. Give readers a clear place to start.

Read the guideView the source

Pass image={{ light, dark, alt }} to provide a variant for each theme. The image follows the theme selected in the header. A string URL or { light, alt } uses one image in both themes; a React element can render an inline illustration.

import { ArdoHero as Hero } from "ardo/ui"

<Hero
  name="My project"
  text="Documentation for your team"
  actions={[{ text: "Read the guide", link: "/guide/getting-started" }]}
/>

Layout and Navigation

The page around these examples is the live layout example: header, section navigation, sidebar, breadcrumbs, article, outline, page actions, and footer. On a narrow screen, open the menu and the on-page outline. Use search and the theme toggle in the header to inspect their real behavior.

See Layout & Navigation for composition examples and Theming to change the palette. The examples inherit those changes without a separate preview theme.