Docs
How to document your components.
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 - Fast, feature-rich documentation framework for Next.js
- Nextra - Markdown-based documentation with built-in search and theming
- Content Collections - Type-safe content management for documentation
- Docusaurus - Feature-rich documentation sites with versioning support
- VitePress - 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, 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 to install the component e.g.
npx shadcn@latest add <your-component-url>If you're publishing to a Marketplace, you can use the marketplace's CLI to install the component e.g.
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, you could build your own CLI to install the component, e.g.
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.
npm install <your-component-name>To show multiple installation options like we've done above, you can use something like Fumadocs' package-install syntax.
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
If you're using Fumadocs, you might consider using Auto Type Table to ensure accuracy and reduce maintenance burden.
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.
If your syntax highlighting framework supports it (like Shiki), you might want to use a diff transformer notation to show the changes between versions.
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