Built-in Components

Rspress provides a powerful set of built-in components that help you create rich, interactive documentation experiences. This chapter explores all available built-in components and how to use them effectively.

Component Overview

Available Components

Rspress includes the following built-in components:

• Layout Components: Tab, Card, Grid
• Content Components: Alert, Badge, Button
• Code Components: CodeBlock, CodeGroup
• Media Components: Image, Video
• Interactive Components: Collapse, Steps
• Navigation Components: Link, TOC

Importing Components

Import components from rspress/theme:

import { Tab, Tabs } from 'rspress/theme';
import { Card } from 'rspress/theme';

Tab Component

Basic Tabs

Create tabbed content:

import { Tab, Tabs } from 'rspress/theme';

<Tabs>
  <Tab label="npm">
    ```bash
    npm install rspress
    ```
  </Tab>
  <Tab label="yarn">
    ```bash
    yarn add rspress
    ```
  </Tab>
  <Tab label="pnpm">
    ```bash
    pnpm add rspress
    ```
  </Tab>
</Tabs>

Default Active Tab

Set the default selected tab:

<Tabs defaultValue="yarn">
  <Tab label="npm" value="npm">
    npm instructions...
  </Tab>
  <Tab label="yarn" value="yarn">
    yarn instructions...
  </Tab>
  <Tab label="pnpm" value="pnpm">
    pnpm instructions...
  </Tab>
</Tabs>

Vertical Tabs

Create vertically-oriented tabs:

<Tabs orientation="vertical">
  <Tab label="Option 1">
    Content for option 1
  </Tab>
  <Tab label="Option 2">
    Content for option 2
  </Tab>
  <Tab label="Option 3">
    Content for option 3
  </Tab>
</Tabs>

Tab Styling

Customize tab appearance:

<Tabs
  variant="pills"  // or "line", "enclosed"
  colorScheme="blue"
>
  <Tab label="Option 1">Content 1</Tab>
  <Tab label="Option 2">Content 2</Tab>
</Tabs>

Card Component

Basic Card

Create content cards:

import { Card } from 'rspress/theme';

<Card title="Feature 1" icon="⚡">
  This is a card with an icon and title.
</Card>

Card Grid

Arrange multiple cards in a grid:

<div className="card-grid">
  <Card title="Fast" icon="⚡">
    Built with Vite for lightning-fast development
  </Card>

  <Card title="Simple" icon="✨">
    Intuitive configuration and minimal setup
  </Card>

  <Card title="Powerful" icon="💪">
    Feature-rich documentation framework
  </Card>

  <Card title="Flexible" icon="🎨">
    Fully customizable themes and components
  </Card>
</div>

Clickable Cards

Cards with links:

<Card
  title="Getting Started"
  href="/guide/getting-started"
  hoverable
>
  Learn how to get started with Rspress
</Card>

Card Variants

Different card styles:

<Card variant="outlined" title="Outlined Card">
  With border, no shadow
</Card>

<Card variant="filled" title="Filled Card">
  With background color
</Card>

<Card variant="elevated" title="Elevated Card">
  With shadow effect
</Card>

Callout Components

Callout Types

VitePress supports different types of callouts for different purposes.

::: tip TIP
This is a helpful tip!
:::

::: info INFO
This provides additional information.
:::

::: warning WARNING
This warns users about potential issues.
:::

::: danger DANGER
This is critical information or dangerous operation.
:::

::: details DETAILS
This is detailed content that can be expanded.
Click to see more...
:::

Custom Titles

You can customize callout titles by adding text after the callout type.

::: tip Pro Tip
You can customize the callout title!
:::

::: warning Important
Remember to backup your data.
:::

Nested Content

Complex content in callouts - you can include lists, code blocks, and other markdown elements inside callouts.

Example structure:

::: info Installation Steps
1. Install dependencies
2. Create config file
3. Run dev server
:::

Code Components

Enhanced Code Blocks

Code blocks with special features:

```javascript title="app.js" showLineNumbers
function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet('World');
```

Line Highlighting

Highlight specific lines:

```javascript {2,4-6}
function calculate(a, b) {
  const sum = a + b;  // Highlighted

  // These lines are highlighted
  if (sum > 100) {
    return 100;
  }

  return sum;
}
```

Code Groups

Combine multiple code snippets:

import { CodeGroup } from 'rspress/theme';

<CodeGroup>
  ```javascript tab="JavaScript"
  const greeting = 'Hello';
  console.log(greeting);
  ```

  ```typescript tab="TypeScript"
  const greeting: string = 'Hello';
  console.log(greeting);
  ```

  ```python tab="Python"
  greeting = 'Hello'
  print(greeting)
  ```
</CodeGroup>

Code Diff

Show code changes:

```diff
function oldFunction() {
-  return 'old value';
+  return 'new value';
}

-const deprecated = true;
+const current = true;
```

Badge Component

Basic Badges

Add status badges:

import { Badge } from 'rspress/theme';

<Badge type="info">New</Badge>
<Badge type="success">Stable</Badge>
<Badge type="warning">Beta</Badge>
<Badge type="danger">Deprecated</Badge>

Inline Badges

Badges in text:

## API Reference <Badge type="info">v3.0+</Badge>

This feature is available in version 3.0 <Badge type="success">Stable</Badge>.

Custom Badges

Custom styled badges:

<Badge
  type="custom"
  style={{
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    color: 'white'
  }}
>
  Premium
</Badge>

Button Component

Basic Buttons

Create action buttons:

import { Button } from 'rspress/theme';

<Button href="/guide/getting-started">
  Get Started
</Button>

<Button
  href="https://github.com/example/repo"
  target="_blank"
  variant="outline"
>
  GitHub
</Button>

Button Variants

Different button styles:

<Button variant="solid">Solid Button</Button>
<Button variant="outline">Outline Button</Button>
<Button variant="ghost">Ghost Button</Button>
<Button variant="link">Link Button</Button>

Button Sizes

Different button sizes:

<Button size="sm">Small Button</Button>
<Button size="md">Medium Button</Button>
<Button size="lg">Large Button</Button>

Button Groups

Combine multiple buttons:

<div className="button-group">
  <Button href="/guide">View Guide</Button>
  <Button href="/api" variant="outline">API Reference</Button>
  <Button href="/examples" variant="ghost">Examples</Button>
</div>

Collapse Component

Basic Collapse

Expandable content:

import { Collapse } from 'rspress/theme';

<Collapse title="Click to Expand">
  This is hidden content that only shows when expanded.

  Can contain any Markdown content:
  - List items
  - Code blocks
  - Other components
</Collapse>

Default Open

Collapse that's open by default:

<Collapse title="FAQ" defaultOpen>
  This content is visible by default.
</Collapse>

Multiple Collapses

Accordion-style collapses:

<Collapse title="Question 1">
  Answer 1
</Collapse>

<Collapse title="Question 2">
  Answer 2
</Collapse>

<Collapse title="Question 3">
  Answer 3
</Collapse>

Steps Component

Step-by-Step Guide

Create step-by-step tutorials:

import { Steps } from 'rspress/theme';

<Steps>

### Step 1: Install

Install Rspress to your project:

`````bash
npm install rspress
```

### Step 2: Configure

Create `rspress.config.ts`:

```typescript
export default defineConfig({
  title: 'My Docs'
});
```

### Step 3: Run

Start the dev server:

```bash
npm run dev
```

</Steps>
````

### Numbered Steps

Custom step numbering:

``````mdx
<Steps start={1}>

### First

Do this...

### Then

Do that...

### Finally

Done!

</Steps>

Image Component

Basic Image

Enhanced image component:

import { Image } from 'rspress/theme';

<Image
  src="/screenshot.png"
  alt="Application screenshot"
  width={800}
  height={600}
/>

Image Zoom

Clickable zoomable images:

<Image
  src="/screenshot.png"
  alt="Application screenshot"
  zoom
  caption="Click to zoom"
/>

Image Grid

Multiple images in a grid:

<div className="image-grid">
  <Image src="/img1.png" alt="Image 1" />
  <Image src="/img2.png" alt="Image 2" />
  <Image src="/img3.png" alt="Image 3" />
  <Image src="/img4.png" alt="Image 4" />
</div>

Link Component

Internal Links

Link to documentation pages:

import { Link } from 'rspress/theme';

<Link href="/guide/getting-started">
  Read the Getting Started Guide
</Link>

External Links

External links with icon:

<Link
  href="https://github.com/example/repo"
  external
>
  View on GitHub
</Link>

Card Links

Large clickable areas:

<Link href="/guide" card>
  <h3>Getting Started</h3>
  <p>Learn the basics of Rspress</p>
</Link>

TOC Component

Page Table of Contents

Display page outline:

import { TOC } from 'rspress/theme';

<TOC />

Custom Depth

Control heading levels:

<TOC
  minDepth={2}
  maxDepth={3}
/>

Grid Layouts

Responsive Grid

Create responsive grid layouts:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <Card title="Item 1">Content 1</Card>
  <Card title="Item 2">Content 2</Card>
  <Card title="Item 3">Content 3</Card>
  <Card title="Item 4">Content 4</Card>
  <Card title="Item 5">Content 5</Card>
  <Card title="Item 6">Content 6</Card>
</div>

Two-Column Layout

Side-by-side content:

<div className="grid grid-cols-2 gap-6">
  <div>
    ### Left Content
    Content on the left...
  </div>

  <div>
    ### Right Content
    Content on the right...
  </div>
</div>

Component Composition

Complex Layouts

Combine multiple components:

<Card title="API Example" icon="📚">
  <Tabs>
    <Tab label="JavaScript">
      ```javascript
      const api = new API();
      api.getData();
      ```
    </Tab>

    <Tab label="Python">
      ```python
      api = API()
      api.get_data()
      ```
    </Tab>
  </Tabs>

  <Badge type="info">v2.0+</Badge>

  ::: tip
  This API was introduced in version 2.0.
  :::
</Card>

Feature Showcase

Showcase product features:

<div className="feature-showcase">
  <Card title="⚡ Fast Development" hoverable>
    Instant HMR and fast builds with Vite

    <Button href="/guide/quick-start">Learn More</Button>
  </Card>

  <Card title="🎨 Fully Customizable" hoverable>
    Customize everything with CSS variables and custom components

    <Button href="/guide/customization">Learn More</Button>
  </Card>

  <Card title="📱 Responsive" hoverable>
    Works perfectly on all devices

    <Button href="/guide/responsive">Learn More</Button>
  </Card>
</div>

Styling Components

Custom Styles

Add custom styles to components:

<Card
  title="Custom Card"
  style={{
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    color: 'white',
    border: 'none'
  }}
>
  Card with custom styling
</Card>

CSS Classes

Use CSS classes:

<div className="custom-container">
  <Card className="custom-card">
    Content...
  </Card>
</div>

CSS:

.custom-container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
}

.custom-card {
  border: 2px solid var(--rp-c-brand);
  border-radius: 12px;
}

Best Practices

Component Usage

1. Consistency: Use components consistently throughout site
2. Accessibility: Ensure all components are accessible
3. Performance: Avoid over-nesting components
4. Semantics: Use semantic HTML

Content Organization

<!-- ✅ Good -->
<Card title="Feature">
  <p>Description...</p>
  <Button href="/docs">Learn More</Button>
</Card>

<!-- ❌ Bad -->
<Card>
  <Card>
    <Card>
      Over-nested...
    </Card>
  </Card>
</Card>

Responsive Design

<!-- Responsive grid -->
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
  <Card>Mobile: 1 col, Tablet: 2 cols, Desktop: 3 cols</Card>
</div>

Troubleshooting

Component Not Rendering

Issue: Component doesn't show

Check:

1. Component imported correctly
2. Component name spelling
3. Props types verified
4. MDX syntax correct

Styling Issues

Issue: Styles not working as expected

Solution:

<!-- ✅ Use className -->
<Card className="my-card">

<!-- ❌ Don't use class -->
<Card class="my-card">

Nesting Issues

Issue: Component nesting problems

Solution:

<!-- ✅ Proper nesting -->
<Tabs>
  <Tab label="Option 1">
    <Card>Content</Card>
  </Tab>
</Tabs>

<!-- ❌ Avoid deep nesting -->
<Tabs>
  <Tab>
    <Card>
      <Collapse>
        <Tabs>...</Tabs>
      </Collapse>
    </Card>
  </Tab>
</Tabs>

---

Next Steps

• Learn about Build Extensions
• Explore Custom Search
• Read about Custom Theme

---

Component Tips

• Always provide alt text for images
• Use semantic HTML for interactive elements
• Test components on mobile devices
• Keep components simple and focused
• Reuse components for consistency

Performance

• Avoid using too many components on one page
• Optimize image sizes
• Lazy load heavy components
• Minimize nesting depth

Resources

• Rspress Component API
• MDX Component Guide
• React Component Best Practices