Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 20 additions & 59 deletions customize/react-components.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,12 @@

import { ColorGenerator } from "/snippets/color-generator.jsx";

[React components](https://react.dev) are a powerful way to create interactive and reusable elements in your documentation.
Build interactive elements in your docs using [React components](https://react.dev) and [hooks](https://react.dev/reference/react/hooks) directly in MDX files.

## Using React components
## Inline components

You can build React components directly in your MDX files using [React hooks](https://react.dev/reference/react/hooks).
Declare components directly in your MDX file:

### Example

This example declares a `Counter` component and then uses it with `<Counter />`.

```mdx
export const Counter = () => {
const [count, setCount] = useState(0)

Expand Down Expand Up @@ -51,58 +46,34 @@
}

<Counter />
```

```mdx
export const Counter = () => {
const [count, setCount] = useState(0)

const increment = () => setCount(count + 1)
const decrement = () => setCount(count - 1)

return (
<div className="flex items-center justify-center">
<div className="flex items-center rounded-xl overflow-hidden border border-zinc-950/20 dark:border-white/20">
<button
onClick={decrement}
className="flex items-center justify-center h-8 w-8 text-zinc-950/80 dark:text-white/80 border-r border-zinc-950/20 dark:border-white/20"
aria-label="Decrease"
>
-
</button>

<div className="flex text-sm items-center justify-center h-8 px-6 text-zinc-950/80 dark:text-white/80 font-medium min-w-[4rem] text-center">
{count}
</div>

<button
onClick={increment}
className="flex items-center justify-center h-8 w-8 text-zinc-950/80 dark:text-white/80 border-l border-zinc-950/20 dark:border-white/20"
aria-label="Increase"
>
+
</button>
</div>
<div>
<button onClick={decrement}>-</button>
<span>{count}</span>
<button onClick={increment}>+</button>
</div>
)
}

The counter renders as an interactive React component.

<Counter />
```

## Importing components

To import React components in your MDX files, the component files must be located in the `/snippets/` folder. Learn more about [reusable snippets](/create/reusable-snippets).
Component files must be in the `/snippets/` folder. Learn more about [reusable snippets](/create/reusable-snippets).

<Note>
Nested imports are not supported. If a React component references other components, you must import all components directly into the parent MDX file rather than importing components within component files.
Nested imports are not supported. Import all referenced components directly into the parent MDX file.
</Note>

### Example

This example declares a `ColorGenerator` component that uses multiple React hooks and then uses it in an MDX file.

Create `color-generator.jsx` file in the `snippets` folder:
Create a component file in `snippets/`:

```mdx /snippets/color-generator.jsx [expandable]
export const ColorGenerator = () => {
Expand Down Expand Up @@ -217,32 +188,22 @@
}
```

Import the `ColorGenerator` component and use it in an MDX file:
Then import and use it:

```mdx
import { ColorGenerator } from "/snippets/color-generator.jsx"

<ColorGenerator />
```

The color generator renders as an interactive React component.

<ColorGenerator />

## Considerations

<AccordionGroup>
<Accordion title="Client-side rendering impact">
React hook components render on the client-side, which has several implications:

- **SEO**: Search engines might not fully index dynamic content.
- **Initial load**: Visitors may experience a flash of loading content before components render.
- **Accessibility**: Ensure dynamic content changes are announced to screen readers.
</Accordion>
<Accordion title="Performance best practices">
- **Optimize dependency arrays**: Include only necessary dependencies in your `useEffect` dependency arrays.
- **Memoize complex calculations**: Use `useMemo` or `useCallback` for expensive operations.
- **Reduce re-renders**: Break large components into smaller ones to prevent cascading re-renders.
- **Lazy loading**: Consider lazy loading complex components to improve initial page load time.
</Accordion>
</AccordionGroup>
- **SEO**: Search engines may not fully index client-rendered dynamic content.
- **Initial load**: Visitors may see a flash before components render.
- **Accessibility**: Ensure dynamic content changes are announced to screen readers.

Check warning on line 205 in customize/react-components.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/react-components.mdx#L205

In general, use active voice instead of passive voice ('are announced').
- **Optimize dependency arrays**: Only include necessary dependencies in `useEffect`.
- **Memoize expensive operations**: Use `useMemo` or `useCallback` where appropriate.
- **Reduce re-renders**: Break large components into smaller ones.
- **Lazy loading**: Lazy load complex components to improve initial page load.
Loading