Skip to main content
Some components solve one narrow problem, like defining a term, formatting a changelog entry, pinning an example beside the content, showing a folder structure, or giving readers a prompt they can copy. Before adding one of these components, identify what problem it solves. If the only reason you’re about to use a component is because “the page looks plain,” text is probably a better choice than a component.

​
Define a term without sending readers away

A tooltip works for a short definition that helps in the moment:
Example of a tooltip
The sentence still makes sense if someone doesn’t open the tooltip. That’s important because hover interactions are easy to miss and work differently on touch devices. Keep instructions and required context in the page itself. A tooltip should save a quick detour, not conceal part of the task. Tooltips can include a link with cta and href, which is useful for pointing to a full definition, but anything readers must follow belongs in the text.

​
Give release notes a consistent shape

The <Update> component is built for dated changelog entries:
Example of a changelog entry
Its label creates an anchor, and its tags help readers filter the changelog. That behavior is useful on a release-notes page but unnecessary inside an ordinary guide. When a product change affects the current instructions, update the guide rather than inserting a permanent release announcement into it.

​
Trade the table of contents for a side panel

<Panel> replaces the page’s table of contents with content you choose, like a reference table or a note that applies to the whole page. Request and response examples already appear in the side panel on their own, so you don’t need a panel just for those. If you do add a panel to an API page, put the examples inside it. That tradeoff is less attractive on a long guide. If readers rely on the table of contents to move between sections, replacing it with a tip or promotional card makes the page harder to navigate. Use a panel when its content supports the entire page and is more useful than section links, not simply because the space is available.

​
Give readers prompts they can actually run

Use <Prompt> when the content is meant to be copied into an AI tool:
Example of a prompt
A useful prompt says what to inspect and what to return. “Improve this page” leaves both decisions to the tool and gives readers little idea what result to expect. If the text is a shell command or code sample, keep it in a code block. The Prompt component is for instructions to an AI tool, not anything that happens to be copyable.

​
Show folder structures as a tree

When readers need to know where files go, a file tree is clearer than a sentence or a code block of indented names. Write a nested list inside <Tree>, with a trailing slash on folder names:
Example of a file tree
Readers can expand and collapse folders, and the tree supports keyboard navigation.

​
Use visual helpers only when they add information

Tiles combine navigation with a visual preview. They work well for a gallery where the preview helps readers choose, such as themes or component examples. If the image adds nothing beyond the title, use a card or a normal link. Icons help distinguish repeated items, but always pair them with a label. A symbol that feels obvious to your team may mean something different to a reader. Color swatches belong in brand and design-system references where the color value is itself the subject. They aren’t a substitute for explaining status or meaning in text. That’s the end of How to use Mintlify components. When you’re unsure about a component, write the content in plain Markdown first. Add the component only if it makes the result easier to find, follow, or understand. Ready for more? Structure docs that scale zooms out from individual components to how your whole site is organized.