---
title: Docs
description: How to document your components.
type: guide
summary: Essential documentation sections for components including demos, installation, API reference, accessibility notes, and changelog.
prerequisites:
  - /composition
related:
  - /registry
  - /npm
  - /marketplaces
---

Good documentation is essential for making your components accessible and easy to use. This guide outlines the key elements every component documentation page should include.

## Documentation Framework

To scale your documentation, you can use a documentation framework. There are many options available depending on your projects' language and project needs. Popular options include:

- [Fumadocs](https://fumadocs.dev/) - Fast, feature-rich documentation framework for Next.js
- [Nextra](https://nextra.site/) - Markdown-based documentation with built-in search and theming
- [Content Collections](https://content-collections.dev/) - Type-safe content management for documentation
- [Docusaurus](https://docusaurus.io/) - Feature-rich documentation sites with versioning support
- [VitePress](https://vitepress.dev/) - Vue-powered static site generator optimized for documentation

Preferably, your framework choice should support syntax highlighting, custom components and be generally well designed.

## Essential Documentation Sections

### Overview

Start with a brief introduction explaining what the component does and when to use it.

### Demo, Source Code, and Preview

For a great first impression for developers, you should include a demo that shows the component in action, as well as the code used to create the demo.

If you're using an open source [Registry](/registry), you can also include a preview of the source code that is used to create the component.

Use code blocks with syntax highlighting and copy-to-clipboard functionality. Consider using tabbed interfaces to switch between these views without cluttering the page.

### Installation

Include a clear instruction on how to install the component. Preferably this should be a single command you can copy and paste into your terminal.

If you're building on shadcn/ui, you can use the [shadcn CLI](https://ui.shadcn.com/docs/cli) to install the component e.g.

```package-install
npx shadcn@latest add <your-component-url>
```

If you're publishing to a [Marketplace](/marketplaces), you can use the marketplace's CLI to install the component e.g.

```package-install
npx shadcn@latest add https://21st.dev/r/<your-author>/<your-component>
```

If you're not using shadcn/ui but you are building a [Registry](/registry), you could build your own CLI to install the component, e.g.

```package-install
npx your-registry-cli@latest add <your-component-url>
```

Lastly, if you're publishing to npm, you can use the npm CLI to install the component e.g.

```package-install
npm install <your-component-name>
```

<Callout>
  To show multiple installation options like we've done above, you can use something like Fumadocs'
  [`package-install` syntax](https://fumadocs.dev/docs/headless/mdx/install).
</Callout>

### Features

List the key features of your component to help users quickly understand its capabilities and advantages. For example:

- **Customizable** – Easily adjust styles, sizes, and behavior to fit your needs.
- **Accessible by default** – Follows best practices for keyboard navigation, ARIA roles, and screen reader support.
- **Composable** – Designed to work seamlessly with other components and patterns.
- **Type-safe** – Ships with comprehensive TypeScript types for maximum safety and autocomplete.
- **Theming support** – Integrates with your design tokens or theme system.
- **Lightweight** – Minimal dependencies and optimized for performance.
- **SSR/SSG ready** – Works with server-side and static rendering frameworks.
- **Well-documented** – Includes clear usage examples and API reference.

Tailor this list to your specific component. Highlight what makes it unique or especially useful for developers.

### Examples

Demonstrate the component's flexibility with practical examples:

- **Variants** - Different visual styles or sizes available
- **States** - Loading, disabled, error, or success states
- **Advanced Usage** - Complex scenarios and edge cases
- **Composition** - How the component works with other components
- **Responsive Behavior** - How it adapts to different screen sizes

Each example should include both the rendered output and the corresponding code.

### Props and API Reference

Document all available props, methods, and configuration options. Consider grouping related props together and highlighting commonly used ones. For each prop, include:

- **Name** - The prop identifier
- **Type** - TypeScript type definition
- **Default** - Default value if not specified
- **Required** - Whether the prop is mandatory
- **Description** - What the prop does and when to use it

<Callout>
  If you're using Fumadocs, you might consider using [Auto Type
  Table](https://fumadocs.dev/docs/ui/components/auto-type-table) to ensure accuracy and reduce
  maintenance burden.
</Callout>

### Accessibility

Document how your component supports accessibility features:

- Keyboard navigation patterns
- ARIA attributes and roles
- Screen reader support
- Focus management
- Color contrast considerations

### Changelog and Versioning

It can be useful to maintain a changelog on each component documentation page covering:

- Version numbers following semantic versioning
- New features and enhancements
- Bug fixes
- Breaking changes
- Migration guides for major version updates

Help users understand what changed between versions and how to upgrade safely. Include code examples showing before/after patterns for breaking changes.

<Callout>
  If your syntax highlighting framework supports it (like Shiki), you might want to use a [diff
  transformer notation](https://shiki.style/packages/transformers#transformernotationdiff) to show
  the changes between versions.
</Callout>

## Best Practices

- Keep documentation up-to-date with code changes
- Use real-world examples that solve actual problems
- Include common pitfalls and troubleshooting tips
- Provide performance considerations when relevant
- Link to related components and patterns
- Make all code examples runnable and tested
