August 28, 2025

Interactive API Documentation: How to Use Custom Components in ReadMe

Trisha Le

UI Engineer

5 minute read

Share on

Learn how to add interactive React components into your docs.

Why Interactive API Documentation Matters

In 2025, documentation doesn’t have to be pages of walls of text. It’s table stakes to learn about APIs through clearly written technical documentation, but now there are tools available to make docs engaging and actually…fun.

How MDX Changes Developer Docs

Traditional content management systems relied on plain text or Markdown. The introduction of MDX changed that by extending Markdown with the ability to embed React components. You’ve probably interacted with a React component today without realizing it. Whether you submitted a form, clicked a button, or even fired off celebratory confetti after completing a task, you interacted with some components on a web page. That same kind of delight can live inside your API docs, giving developers not just instructions but a hands-on experience.

Two Ways to Add Components in ReadMe

With ReadMe’s editor, you can add components to your documentation in two ways:

Use built-in components like Cards or Accordions, easily accessible from the slash menu.
Build your own components and bring them directly into your docs.

Examples of Components

Here are some of my favorite components:

Accordion: Expand and collapse sections of content to organize and display large amounts of information in a compact, interactive way.

Specs & Details

A great way to collapse information, but ensure essential headers are still visible.

FAQ

Use accordions in FAQs to break down content in a way that's easy to find and digestible.

Page Banners: Visually highlight important information, announcements, or calls to action directly inside a page. Customize the message, text, and colors, as well as the position whether it's inline (inside the content body) or at the top of the page header.

This banner is displayed inline.

Quiz Game: Display a question with multiple-choice answers, let the user select an option, and check if the answer is correct.

What is a group of owls called?

Here's the code you would paste into your component editor in ReadMe:

import { useState } from 'react';

export const QuizGame = ({ question, options }) => {
  const [selectedIndex, setSelectedIndex] = useState(null);
  const [submitted, setSubmitted] = useState(false);

  const handleOptionClick = (index) => {
    if (submitted) return;
    setSelectedIndex(index);
  };

  const handleSubmit = () => {
    if (selectedIndex !== null) {
      setSubmitted(true);
    }
  };

  const handleReset = () => {
    setSelectedIndex(null);
    setSubmitted(false);
  };

  return (
    <div className="max-w-md mx-auto p-6 bg-inherit rounded-lg shadow-sm border border-gray-200 dark:border-gray-400">
      <h3 className="mb-6! mt-0! text-center">{question}</h3>
      <div className="flex flex-col gap-2">
        {options.map((option, idx) => (
          <button
            key={idx}
            onClick={() => handleOptionClick(idx)}
            className={`
              text-sm text-left border-0 rounded-md p-[10px] bg-gray-100 text-gray-600 dark:bg-gray-700 dark:text-white
              ${!submitted && 'cursor-pointer hover:bg-gray-200 dark:hover:bg-gray-700'}
              ${!submitted && selectedIndex === idx && 'border! border-blue-300 bg-blue-200! dark:bg-blue-900!'}
              ${submitted && option.isCorrect && 'border! border-green-300 bg-green-100 dark:bg-green-900'}
              ${submitted && selectedIndex === idx && !option.isCorrect && 'border! border-red-300 bg-red-100 dark:bg-red-900'}
            `}
          >
            {option.text}
          </button>
        ))}
      </div>
      <div className="flex justify-end">
        {!submitted ? (
          <button
            onClick={handleSubmit}
            disabled={selectedIndex === null}
            className={`
              mt-3 border-none p-3 font-semibold rounded-md cursor-pointer
              ${submitted || selectedIndex === null ? 'bg-gray-300 text-gray-400 cursor-not-allowed!' : 'bg-blue-500 text-white hover:bg-blue-600'}
            `}
          >
            Check Answer
          </button>
        ) : (
            <button
              onClick={handleReset}
              className="mt-3 border-none py-3 px-7 font-semibold rounded-md cursor-pointer text-white bg-gray-500 hover:bg-gray-400"
            >
              <i className="fa-solid fa-refresh" /> Reset
            </button>
          )}
        </div>
      </div>
    );
  };

<QuizGame
  question="What is a group of owls called?"
  options={[
    { text: 'A flock', isCorrect: false },
    { text: 'A parliament', isCorrect: true},
    { text: 'A council', isCorrect: false },
    { text: 'A murder', isCorrect: false }
  ]}
/>

How to Add a Component to Your Documentation

In your Admin Dashboard, go to Settings > Custom Components.
From the Marketplace, choose a component to customize. Or, you can build your own component from scratch with JSX!
Add the component to your docs using the < menu.

Share Your Component with ReadMe's Community

If you've built a component and want to contribute it to our Component Marketplace on GitHub, open up a PR with your new MDX component and we'll review it! Here are our Contribution Guidelines if you're interested in contributing to ReadMe's Component Marketplace. If you have any questions, just open an issue.

Need help building components, or want to contribute a component to our marketplace?

Join our Slack channel