# Custom React components

> Add custom React components to your Fern docs for interactive, server-rendered elements. Improve SEO, performance, and user experience with reusable components.

<Warning title="Pro and Enterprise feature">
  This feature is available only for the [Pro and Enterprise plans](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).
</Warning>

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.

<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>

## How it works

<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 start leveraging it in your Markdown guides.

  ```jsx guide.mdx
  import { CustomCard } from "../components/CustomCard"

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

  ### 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>