***

title: Custom React components
description: >-
Add custom React components to your Fern docs for interactive, server-rendered
elements. Improve SEO, performance, and user experience with reusable
components.
slug: customization/custom-react-components
-------------------------------------------

For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see [https://buildwithfern.com/learn/llms.txt](https://buildwithfern.com/learn/llms.txt). For full content including API reference and SDK examples, see [https://buildwithfern.com/learn/llms-full.txt](https://buildwithfern.com/learn/llms-full.txt).

You can extend Fern's built-in component library by adding your own custom React components. This allows you to create unique, interactive elements that match your documentation needs. Components are server-side rendered for better SEO and performance, with no layout shifts.

<Note title="Defining a constant">
  Don't use a React component to define a constant. Instead, consider using [reusable snippets](/docs/writing-content/reusable-snippets).
</Note>

## Custom components in MDX

<Steps>
  ### Create a React component

  Let's start by creating a `components` folder where you can define your React components. Note
  that the React components can be defined in `.ts`, `.tsx`, `.js` or `.mdx` files.

  ```ts components/CustomCard.tsx 
    export const CustomCard = ({ title, text, link, sparkle = false }) => {
        return (
            <a href={link} className="block p-6 rounded-lg border border-gray-200 hover:shadow-lg transition-shadow">
            <h2 className="text-xl font-semibold mb-2">
                {title} {sparkle && "✨"}
            </h2>
            <p className="text-gray-600">{text}</p>
            </a>
        );
    };
  ```

  ### Use the component in your docs

  Once you've written the component, you can import it in your Markdown guides using either a relative path or the `@/` prefix for an absolute path from your fern folder root:

  ```jsx guide.mdx
  // Absolute path from fern folder root
  import { CustomCard } from "@/components/CustomCard"

  // Or use a relative path
  import { CustomCard } from "../components/CustomCard"

  <CustomCard 
    title="MyTitle" 
    text="Hello" 
    href="https://github.com/fern-api/fern/tree/main/generators/python"
  />
  ```

  The `@/` prefix resolves to the root of your fern folder, so `@/components/CustomCard` refers to `fern/components/CustomCard`. This is useful for nested MDX files where relative paths would be cumbersome (e.g., `../../../components/CustomCard`). Both import styles are automatically transformed to relative paths at publish time.

  ### Specify your components directory in `docs.yml`

  Add your components directory to `docs.yml` so that the Fern CLI can scan your components directory
  and upload them to the server.

  ```yml docs.yml
  experimental:
    mdx-components:
      - ./components
  ```
</Steps>

## Why not just use custom CSS and JS instead?

While you can bundle React components as custom JavaScript, using Fern's built-in React component support provides several key advantages:

<AccordionGroup>
  <Accordion title="No layout shifts or flashes">
    When adding React components via custom JavaScript, you can't control when components are rendered relative to the rest of the page content. This often leads to glitchy behavior where components flash or
    jump as they load asynchronously after the main content.
  </Accordion>

  <Accordion title="Faster page load">
    Custom JavaScript bundles typically include their own copy of the React library, which:

    * Increases page load time by duplicating React code that's already included
    * Reduces performance as multiple React instances run on the same page
    * Creates larger bundle sizes that users have to download
  </Accordion>

  <Accordion title="Improved SEO">
    Custom React components are server-side rendered and fully indexable by search engines, while components added via custom JavaScript aren't server-side rendered and can't be indexed.
  </Accordion>
</AccordionGroup>