# MDX component reference
Use Plandalf's Mintlify-style MDX components for implementation guides, API docs, examples, prompts, cards, tiles, and agent-aware content.
Source: /docs/components/reference
Last modified: 2026-06-20
This page is the authoring reference for Plandalf docs components. It focuses on the MDX you write, not every visual variation in the showcase.


> **Porting Mintlify-style MDX**
>

  Plandalf supports the same core component families used in Mintlify-style documentation: structure, callouts, API fields, examples, cards, tiles, icons, diagrams, updates, and visibility controls. Use [MDX component showcase](/docs/components/showcase) when you need visual QA.


## Component families


  - [Structure](#structure): Steps, tabs, code groups, columns, panels, accordions, and expandables.
  - [Attention](#attention): Callouts, banners, badges, updates, tooltips, and snippets.
  - [API docs](#api-docs): Fields, response fields, request examples, response examples, and API summaries.
  - [Navigation](#navigation): Cards and tiles for next-page choices.
  - [Visual context](#visual-context): Frames, images, icons, Mermaid diagrams, trees, and color swatches.
  - [Audience targeting](#audience-targeting): Human-visible and agent-visible content blocks.


## Mintlify parity map

The public docs component surface is intentionally shaped around Mintlify's MDX catalog. Prefer these primitives before adding one-off markup to a docs page.


### Current Mintlify component catalog


- `Structure your content` (Tabs, CodeGroup, Steps, Columns, Panel):
    Use these when the reader is moving through a procedure, switching language/framework context, or keeping supplementary detail near the guide.


- `Draw attention` (Callout, Banner, Badge, Update, Frame, Tooltip):
    Use these for emphasis, page-level notices, inline status, release notes, framed media, and definitions.


- `Showcase AI prompts` (Prompt):
    Use prompts for copyable agent instructions, with optional copy and Cursor actions.


- `Show and hide content` (AccordionGroup, Accordion, Expandable, View, Visibility):
    Use disclosure components when the page should teach progressively or expose separate human and agent context.


- `Document your API` (Fields, ParamField, Responses, ResponseField, Examples):
    Use these for API page frontmatter, endpoint headers, request fields, response shapes, nested objects, and request/response examples.


- `Link to other pages` (Card, CardGroup, Tile, TileGroup):
    Use cards for a few high-value next steps and tiles for denser icon grids. Every linked tile should carry an icon.


- `Add visual context` (Icon, Mermaid, Color, Tree, DocsImage):
    Use visual primitives for icons, diagrams, color swatches, file trees, screenshots, and embedded media.


## Coverage checklist

Use this table when porting Mintlify-style MDX into Plandalf docs. `Native` means the same component name is registered. `Alias` means common imported names map to the Plandalf component. `Extension` means the component is Plandalf-specific but useful beside Mintlify-style docs.

| Mintlify area | Plandalf MDX support | Status |
| --- | --- | --- |
| Accordions | `AccordionGroup`, `Accordion`, `Accordions` | Native + alias |
| Badge | `Badge` | Native |
| Banner | `Banner` | Native |
| Callouts | `Callout`, `Note`, `Info`, `Tip`, `Warning`, `Check`, `Danger` | Native + aliases |
| Cards | `Card`, `CardGroup`, `Cards`, `CardGrid` | Native + aliases |
| Code formatting | fenced code, `CodeBlock` | Native |
| Code groups | `CodeGroup`, `CodeGroups`, `CodeTabs`, `CodeBlocks`, `CodeBlockGroup` | Native + aliases |
| Lists and tables | Markdown lists, task lists, tables | Native |
| Color | `Color`, `Color.Item`, `Color.Row`, `ColorPalette`, `ColorSwatch`, `Swatch`, `PaletteRow` | Native + aliases |
| Columns | `Columns`, `Column` | Native |
| Examples | `Examples`, `Example`, `RequestExample`, `ResponseExample` | Native |
| Expandables | `Expandable` | Native |
| Fields | `Fields`, `ParamField`, `Field`, `Param`, `Parameter`, `Property`, `RequestField`, `RequestFields`, `ParamFields` | Native + aliases |
| Frames | `Frame` | Native |
| Headings | `Heading` | Native |
| Icons | `Icon` | Native |
| Mermaid | `Mermaid` | Native |
| Panel | `Panel` | Native |
| Prompt | `Prompt` | Native |
| Snippet | `Snippet` | Plandalf extension |
| Manual API pages | `api`, `openapi`, `openapi-schema`, `ApiReferenceHeader`, `ApiEndpoint` | Native + frontmatter |
| Response fields | `Responses`, `ResponseField`, `Response`, `ResponseFields`, `ResponseFieldGroup` | Native + aliases |
| Steps | `Steps`, `Step` | Native |
| Tabs | `Tabs`, `Tab` | Native |
| Tiles | `Tile`, `TileGroup`, `Tiles`, `TileGrid` | Native + aliases |
| Tooltips | `Tooltip` | Native |
| Tree | `Tree`, `Tree.Folder`, `Tree.File`, `Folder`, `File` | Native + aliases |
| Update | `Update` | Native |
| View | `View` | Native |
| Visibility | `Visibility` | Native |

## Exact prop parity

Use this section when importing Mintlify-style MDX or writing examples that should behave like Mintlify without custom wrappers.


### Mintlify props covered in Plandalf


- `Cards` (title, icon, iconType, color, href, horizontal, img, cta, arrow, type):
    `Card` and `CardGroup` support linked cards, image cards, horizontal cards, typed cards, icon color, CTAs, arrows, and grouped grids.


- `Code groups` (labels, title, dropdown, sync):
    `CodeGroup` reads fenced-code languages and labels, supports a dropdown selector, and syncs matching language choices across tabs and code groups unless disabled.


- `Code formatting` (title, filename, lines, wrap, highlight, focus, diff, expandable):
    Fenced code blocks render Mintlify-style headers, copy controls, language labels, line numbers, highlighted or focused lines, diff markers, wrapping, and expandable long snippets.


- `Lists and tables` (ordered lists, nested lists, task lists, Markdown tables):
    Markdown lists and tables render with Plandalf docs styling. Use them for compact structure before adding heavier cards, accordions, or fields.


- `Examples` (RequestExample, ResponseExample, dropdown, right rail):
    Request and response examples can render inline on mobile and in the desktop right rail. API pages bind examples to the active endpoint.


- `Tiles` (href, title, description, children, icon, img):
    `Tile` supports compact icon links, image preview tiles, child media previews, descriptions, and tracked media-library images.


- `Steps` (titleSize, icon, iconType, stepNumber, id, noAnchor):
    `Steps` and `Step` support numbered procedures, icon markers, explicit step numbers, anchorable step titles, and imported heading sizes.


- `Tabs` (defaultTabIndex, sync, borderBottom, title, id, icon, iconType):
    `Tabs` and `Tab` support default selection, shared sync state, bottom-border styling, anchors, and icon props.


- `Manual API pages` (api, authMethod, playground):
    `api` frontmatter renders a Mintlify-style endpoint header. `authMethod` and `playground` control authentication labels and whether the endpoint area is simple, interactive, or hidden.


### Plandalf docs renderer extensions


- `DocsImage` (img replacement):
    Markdown and MDX images render through `DocsImage`, which preserves standard image attributes and adds zoom metadata.


- `MediaImage` (media library image):
    Use MediaImage or MediaScreenshot when a docs page needs a tracked screenshot or generated asset from the site media library.


- `CodeBlock` (manual code block):
    Use this only when a fenced block cannot express the needed metadata. Normal fenced code blocks already support language, title, filename, lines, wrap, highlight, and focus metadata.


- `CodeSwitcher` (sample switcher):
    Use CodeSwitcher for data-driven language samples when the examples are not authored as ordinary fenced code inside a CodeGroup.


- `ApiSurface` (API summary):
    Use ApiSurface for compact endpoint summaries before detailed fields and examples.


- `ApiReferenceHeader` (API page header):
    Mintlify-style `api`, `openapi`, or `openapi-schema` frontmatter renders this automatically. Use it manually only for compatibility tests.


- `CodeExplainer` (annotated snippet):
    Use CodeExplainer when a code sample needs named notes beside the snippet.


- `VisualFlow` (process diagram):
    Use VisualFlow for lightweight implementation flows when Mermaid would be too formal.


### Supported component families


- `Structure` (Steps, Tabs, Tab, CodeGroup, Columns, Column, Panel):
    Use these for procedures, language or framework choices, side-by-side content, and right-rail context. Tabs and code groups synchronize matching labels unless sync is disabled.


- `Attention` (Callout, Note, Tip, Info, Warning, Check, Danger, Banner, Badge, Update, Tooltip):
    Use these for notices, release notes, labels, and inline definitions instead of turning every warning into a card.


- `Disclosure` (AccordionGroup, Accordion, Expandable, View, Visibility):
    Use these when detail should unfold gradually or when a page needs separate human and agent-visible content.


- `API reference` (api, openapi, openapi-schema, Fields, ParamField, Responses, ResponseField, Examples):
    Use Mintlify-style `api` frontmatter, or `openapi` for existing Plandalf docs, when the whole page is an endpoint. Then document request parameters, nested objects, response payloads, and side-by-side request/response samples.


- `Navigation` (Card, CardGroup, Tile, TileGroup):
    Use cards for a small number of important next steps and tiles for denser icon or preview grids.


- `Visual context` (Frame, DocsImage, Icon, Mermaid, Tree, Color):
    Use these for screenshots, embeds, diagrams, file structures, icons, and literal color values.


## Structure

Use structure components when a reader needs to move through a sequence, choose a platform, compare snippets, or reveal optional detail.


### Structure components


- `Steps` (component):
    Wrap ordered Step items. Use `titleSize`, `stepNumber`, `id`, `noAnchor`, `icon`, and `iconType` when ported procedures need exact marker, heading, and anchor behavior.


- `Heading` (component):
    Render Mintlify-style explicit headings with `level`, `id`, and `title` props when ported MDX uses component headings instead of Markdown heading syntax.


- `Tabs` (component):
    Wrap Tab panels with a title prop. Matching tab titles synchronize across the page unless `sync={false}` is set.


- `CodeGroup` (component):
    Wrap multiple fenced code blocks. Use `labels`, fenced-code titles, `dropdown`, and `sync={false}` when needed.


- `Columns` (component):
    Wrap Column items for side-by-side prose, fields, tables, or snippets without adding another card surface.


- `AccordionGroup` (component):
    Group related Accordion items. Opening an accordion updates the URL hash for direct links, and `icon`/`iconType` pass through to the shared icon renderer.


- `Expandable` (component):
    Reveal nested API properties or secondary implementation detail.


### Structure examples


```mdx Steps


### Create the offer


    Start with one test offer.


### Open checkout


    Connect one button to that offer.


```

```mdx Tabs


### HTML


    Use the browser SDK on static pages.


### React


    Use the React wrapper inside an app.


### Agent


    Lucide package icons render through the same shared icon path as cards, badges, and inline icons.


```

````mdx CodeGroup

### Install options


```html
<script src="https://cdn.plandalf.com/sdk.js" defer></script>
```

```bash
npm install @plandalf/browser
```


````


### Component heading example


The `Heading` component keeps imported Mintlify MDX readable without rewriting every explicit heading into Markdown.


### Numbered step


    Mintlify-style numbered steps keep a clean rail and direct anchor target for procedural docs. Parent-level `titleSize` upgrades the rendered step title element, not only the visual size.


### Continue at step five

Imported MDX can override the number.


    Use `stepNumber` when a ported procedure continues from a previous sequence.


### Icon step


    Use `icon` and `iconType` when the marker should be a visual signal instead of a number.


### Imported icon name


    Common Mintlify example icons render through the Plandalf icon layer instead of falling back to a generic document mark.


```js Inline highlight example {1,4} lines
const offerId = "offer_123";
const mode = "modal";

await window.Plandalf.openOffer({ offerId, mode });
```


### HTML


    Use the browser SDK on static pages.


### React


    Use the React wrapper inside an app.


### Agent


    Package Lucide icons render through the same shared icon path as cards, badges, and inline icons.


### Synced language choice


```js JavaScript
await window.Plandalf.openOffer({ offerId: "offer_123" });
```

```python Python
client.offers.open("offer_123")
```


### JavaScript


    Selecting this tab syncs matching `CodeGroup` examples on the same page.


### Python


    Matching labels update together, like Mintlify language tabs.


### Synced language choice


```js JavaScript
window.Plandalf.on("checkout.completed", (event) => {
  console.log(event.checkoutId);
});
```

```python Python
for event in client.events.list(type="checkout.completed"):
    print(event.checkout_id)
```


### Unsynced language choice


```js JavaScript
console.log("This group keeps its own selection.");
```

```python Python
print("This group ignores page-level language sync.")
```


### Language alias labels


```py
client.offers.open("offer_123")
```

```yml
offer:
  id: offer_123
```

```http
POST /checkout/sessions HTTP/1.1
Host: api.plandalf.com
```


### Dropdown selector


```html HTML
<button data-plandalf data-offer="offer_123">Buy now</button>
```

```tsx React
<PlandalfButton offerId="offer_123">Buy now</PlandalfButton>
```


### Imported code-block group alias


```js JavaScript
await plandalf.offers.open("offer_123");
```

```bash Shell
curl "https://api.plandalf.com/api/offers/offer_123"
```


### alias-labels.yml


```yml
plandalf:
  offer: offer_123
  mode: test
```


> **Accordion icon compatibility**
>

    Use path icons, Lucide names, or inline SVG-compatible icon values where a page needs a more specific visual marker.


> **Open by default**
>

    Mintlify-style `defaultOpen` support keeps imported accordion state intact and still updates the URL hash when a reader opens another item.


### Expandable object


- `user` (User Object):
    Returned when a checkout has an attached customer profile.


> **properties**
>


- `full_name` (string):
        The buyer's display name.


- `is_over_21` (boolean):
        Whether age-gated offer checks passed.


## Attention

Use attention components when a detail must stand out but should not become a marketing card.


> **Named aliases**
>

      Use Note, Tip, Warning, Info, Check, and Danger when generated or imported MDX names the callout directly.


> **Inline status**
>

      Use Badge for small labels in prose and field descriptions.


      Badge variants match Mintlify-style inline metadata: Verified
      Beta
      Locked


> **Page-level notice**
>

      Use banners for page-wide notices, preview warnings, or release notes that should sit above the guide.


> **Maintenance notice. Update your webhook endpoint before switching traffic.**
>
>


> **Component update**
>
> Use updates for dated changes or changelog-like notes inside docs.

> Docs, MDX


### Attention component props


- `Badge` (color, size, shape, icon, iconType, stroke, disabled, tooltip):
    Use badges inline for statuses, version labels, and short metadata. Supported colors include gray, blue, green, yellow, orange, red, purple, white, surface, white-destructive, and surface-destructive.


- `Banner` (content, dismissible, type, color):
    Use banners for page-level announcements. Dismissible banners stay hidden until their rendered content changes. Custom `color` objects render as solid white-text banners, matching Mintlify's announcement banner behavior.


- `Callout` (icon, iconType, color):
    Use the generic callout for custom icon and color combinations. Typed callouts such as Note, Warning, Info, Tip, Check, and Danger keep preset tones.


    Gray
    Blue
    Green
    Yellow


    Orange
    Red
    Purple
    Surface


    Premium
    Verified
    Disabled


    White
    White destructive


    Surface destructive
    XS
    MD


    Blocked
    Alert
    Self closing label


> **Custom color banner**
>
> Banners accept Mintlify-style color objects and preserve iconType metadata.
>


    This draws attention to important information.

    This confirms a completed or supported setup.


    This raises a warning to watch out for.

    This is a danger callout.


    cols
    Columns accept numeric strings and clamp to the documented 1-4 range.


    span
    Column can span multiple tracks when one item needs more room for prose or code.


    gap
    Use gap and align to tune layout density without adding card wrappers.


```mdx

> **Do this in test mode first**
>

  Open checkout with a test offer before connecting live payment traffic.


Offer


  Custom callouts can use an icon and color without forcing a default Note heading.


```

Inline definitions can keep readers oriented before they leave the page. For example, an Offer is the customer-facing checkout surface.


  Custom callouts can use an icon and color without forcing a default Note heading.


> **Generate clear, concise implementation docs for Offers.**
>

You are a technical writing assistant. Rewrite this Plandalf implementation guide so a developer can ship one small working integration first, then deepen the setup.


## API Docs

Use API components when documenting parameters, nested objects, response fields, and request or response samples.

Explicit `optional` props render as neutral field metadata and are preserved in Markdown export. Unmarked fields stay unlabelled, matching Mintlify's quieter default field presentation.

Mintlify-style manual API pages can declare the endpoint in frontmatter. Plandalf renders the API reference header automatically before the page body.

```mdx Manual API page
---
title: "Check the active identity"
description: "Validate a bearer token and return the current organization."
section: "API"
api: "GET /api/users/me"
operationId: "getCurrentUser"
---
```

Use `openapi: "GET /api/users/me"` for existing Plandalf pages that already use the OpenAPI-style name. Use `openapi-schema: "SchemaName"` when the page documents a reusable OpenAPI data model instead of a request endpoint.


### Request parameters


- `offerId` (string; required):
    Path parameter for the offer being opened or retrieved.


- `include` (string[]; array, optional, default: [], expandable):
    Optional expansions such as line items, invoices, or customer records.


- `coupon` (string; placeholder: SUMMER25):

- `Idempotency-Key` (string):
    Header value used to make repeated backend requests safe.


- `legacyCustomerId` (string; deprecated):

- `customer` (object):
    Buyer context sent with checkout.


- `customer.email` (string):
      Email used for receipts and buyer matching.


### Alias request fields


- `customer.email` (string; required):
    Imported API MDX can use `RequestField` for a single request body field.


- `include` (string[]; optional):
    `RequestParam` keeps request terminology while rendering through the same field row.


- `metadata.campaign` (string):
    `RequestProperty` works for schema-style request bodies.


- `aliasParam` (string; optional):
    Imported MDX can use `param` as the field key when the request location is not important.


- `aliasOfferId` (string; alias, required):
    Imported MDX can wrap parameter-like rows with `RequestFields` and use `Property` for individual fields.


- `aliasInclude` (string[]; export):
    Alias wrappers are preserved in the web render and converted into useful bullets in Markdown export.


### Plural parameter alias


- `offerId` (string; required):
    `ParamFields` and `RequestParameter` cover imported docs that spell out request parameters.


### Response shape


- `aliasResponse` (object; optional):
    Imported response rows can use `response` as the key and still render as a response field.


- `checkoutId` (string; data, required):
    Identifier for the checkout session.


- `status` ("open" | "completed" | "expired"; optional, enum):
    Current state of the checkout session.


- `legacyStatus` (string; deprecated, legacy):

- `offer` (object):
    Expanded offer details.


> **properties**
>


- `offer.id` (string):
        Offer identifier.


- `offer.currency` (string; default: usd):
        Checkout currency.


### Response alias group


- `data.id` (string; required):
    `ResponseFieldGroup` maps to the same response container as `Responses`.


### Create checkout session


```bash cURL
curl --request POST \
  --url https://api.plandalf.com/checkout/sessions \
  --header "Authorization: Bearer $PLANDALF_API_KEY" \
  --json '{"offer_id":"offer_123"}'
```

```js Fetch
await fetch("https://api.plandalf.com/checkout/sessions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PLANDALF_API_KEY}` },
  body: JSON.stringify({ offer_id: "offer_123" }),
});
```


### Checkout session response


```json Response
{
  "data": {
    "checkoutId": "checkout_123",
    "status": "open"
  }
}
```


### Alias-labeled request examples


```py
client.offers.open("offer_123")
```

```yml
offer:
  id: offer_123
```

```http
POST /checkout/sessions HTTP/1.1
Host: api.plandalf.com
```


### Inline request and response


### Tabbed request


```bash cURL
curl --request POST \
  --url https://api.plandalf.com/checkout/sessions \
  --json '{"offer_id":"offer_123"}'
```

```js JavaScript
await fetch("https://api.plandalf.com/checkout/sessions", {
  method: "POST",
  body: JSON.stringify({ offer_id: "offer_123" })
});
```


### Dropdown response


```json Success
{ "status": "open" }
```

```json Expired
{ "status": "expired" }
```


## Navigation

Use cards for a few important next steps. Use tiles for denser grids where every item needs an icon and a short description.

Mintlify commonly groups cards with `Columns` and places the card copy in children. Plandalf supports that pattern directly.


### Card and tile props


- `Card` (title, icon, iconType, color, href, cta, arrow, horizontal, img, type):
    Cards support Mintlify-style linked containers, horizontal cards, image cards, typed callout cards, custom CTA text, arrows, and icon color overrides.


- `Tile` (href, title, description, children, icon, img):
    Tiles support preview children and image props. `title` is optional for imported Mintlify visual tiles, but Plandalf docs should still use titles for navigation grids.


- `Groups` (Columns, CardGroup, TileGroup):
    Use `Columns` when porting Mintlify examples directly. Use `CardGroup` or `TileGroup` when authoring dense Plandalf docs grids with consistent spacing.


### Horizontal card


    Use `horizontal` when a card should read as a compact row instead of a full preview block.


### Image card


    Mintlify-style `img` and `alt` props render through the Plandalf media surface.


### Note card


    Use `note` when grouped content should inherit callout-style styling.


### Warning card


    Use `warning` to flag a risky setup without building a custom callout.


### Tip card

Expression prop searchable fixture


    Override the default typed card icon when a ported page already provides one.


### [Get started](/docs/quickstart)


    Set up one buy button, open one test offer, and handle the checkout result.


### [API reference](/docs/api/reference)


    Explore endpoints, request fields, response fields, and backend integration examples.


  - [Offers overview](/docs/offers/overview): Learn the checkout surface first.
  - [Webhooks](/docs/api/webhooks): Route purchase context to backend systems.


  - [Alias-friendly cards](/docs/components/showcase): Use `CardGrid` when imported docs expect a grid wrapper name.
  - [Layer card variant](/docs/components/showcase): Layer cards keep the Kumo-style surface without nested containers.


  - [Lucide package icon](/docs/components/showcase): Imported Mintlify cards can use broader Lucide icon names without falling back to the document icon.
  - [Prefixed Lucide icon](/docs/components/showcase): The `lucide:` prefix and camel/kebab casing normalize to the installed icon package.


### [Forced internal arrow](/docs/components/showcase)


    Use `arrow` when an internal link needs the same affordance as an external card.


### [External card without arrow](https://example.com)


    Use `arrow={false}` when a ported Mintlify card deliberately hides the arrow.


### [CTA without arrow](/docs/components/showcase)


    CTA labels can stay text-only when the surrounding grid is already visually busy.


  - [SDK install](/docs/sdk/install): Load the browser package.
  - [React SDK](/docs/sdk/react): Use Plandalf in React.
  - [Webflow](/docs/platforms/webflow): Add buying actions to Webflow.


  - [Image prop tile](/docs/components/showcase): Tiles accept `img`, `alt`, and `columns` aliases from imported MDX.
  - [Icon tile](/docs/components/showcase): Use icon tiles for dense navigation where preview media would be too heavy.


Mintlify-style tiles can also place a visual child inside the tile. Plandalf detects image, SVG, video, iframe, and picture children and renders them in the preview area automatically.


### [Mintlify child image tile](/docs/components/showcase)

Imported image children can use className and still render as preview media.


    ![Plandalf logo preview](/logo.svg)


### [Preview child tile](/docs/components/showcase)

Child images are promoted to the visual preview area.


    ![Checkout element palette preview.](/images/features/checkout-templates/checkout-elements-palette-product.png)


### [Inline SVG preview](/docs/components/showcase)

Inline SVG children work as portable preview art.


    [Layered checkout blocks]


### [Imported preview tile](/docs/components/showcase)

A visual child can carry the preview when imported MDX started with media-first markup.


    [Title-less preview tile]


## Visual Context

Use visual components when the reader needs to understand a screen, file structure, flow, or literal value.


### Visual component props


- `Frame` (caption, hint):
    Frames support Markdown captions and hints. Autoplay videos inside a frame are enhanced with `playsInline`, `loop`, and `muted` attributes.


- `Tree.Folder` (name, defaultOpen, openable):
    Folders can be expanded by default or made non-interactive with `openable={false}`. Tree nodes support keyboard navigation for visible items.


- `Update` (label, description, tags, rss):
    Updates create anchorable changelog entries. Use `rss` when the visual update contains components or HTML that need a plain-text feed fallback.


  ![The Numi offer editor screen.](/images/stacks/api-first/numi-offer-editor.png)


- content/docs/


- introduction.mdx


- quickstart.mdx


- components/


- reference.mdx


- showcase.mdx


- generated/


- llms.txt.ts


  Added reference examples for Mintlify-style visual components, including a frame, file tree, and RSS-safe update metadata.


> **Pinned implementation context**
>

  Mintlify-style `Panel` content moves into the right rail and replaces the table of contents on desktop. Keep request and response examples inside the panel when the panel owns the rail.


> **Inline panel**
>

    Use `placement="inline"`, `inline`, or `rail={false}` when the panel should stay in the document flow.


> **Rail disabled**
>

    Inline panels are useful for compact local context without replacing the right rail.


### Checkout handoff

```mermaid

flowchart LR
  Site[Website] --> SDK[Plandalf SDK]
  SDK --> Offer[Offer checkout]
  Offer --> Event[Browser event]
  Offer --> Webhook[Webhook]

```


### Controls hidden

```mermaid

flowchart LR
  HiddenButton[Buy button] --> HiddenOffer[Offer]
  HiddenOffer --> HiddenComplete[Completion]

```


### Controls pinned top left

```mermaid

flowchart LR
  PinnedPage[Sales page] --> PinnedTimer[Timer state]
  PinnedTimer --> PinnedOffer[Offer checkout]
  PinnedOffer --> PinnedBackend[Backend workflow]

```


Inline icons keep Mintlify-style size, color, path, SVG, library prefixes, and `iconType` props: [icon: flag] [icon: fa:circle-info] [icon: tabler:brand-react] [icon: /platforms/stripe.svg] [icon: [SVG preview]].


### Inline primitive props


- `Icon` (icon, iconType, color, size, className):
    Icons can use bundled names, Lucide names, common Font Awesome or Tabler-style aliases, external URLs, project paths, custom colors, and pixel sizes inside prose or headings.


- `Tooltip` (tip, headline, cta, href):
    Tooltips attach definitions to inline terms and can include a CTA link when a reader needs a deeper concept page.


- `Snippet` (text, label, icon, copy):
    Snippets show compact copyable values such as package names, environment variables, endpoints, and command fragments.


Use snippets for copyable inline values such as `PLANDALF_API_KEY` and `@plandalf/browser` without turning the surrounding paragraph into a code block.


- hex: #0f8f8c


- rgb: rgb(15, 143, 140)


- rgba: rgba(15, 143, 140, 0.72)


- hsl: hsl(179, 81%, 31%)


- oklch: oklch(58% 0.12 185)


- theme pair: { light: "#ffffff", dark: "#0f172a" }


#### Brand


- Primary: #0f8f8c


- Primary soft: #ccfbf1


#### Surfaces


- Canvas: { light: "#ffffff", dark: "#0f172a" }


- Aqua wash: #effdfb


## Renderer Extensions

These components are Plandalf-specific helpers that sit beside the Mintlify-style surface. Use them when the docs need richer product context without inventing one-off HTML.


### Offer SDK surface

Use API surfaces for compact method summaries before detailed fields and examples.

- [Open an offer](/docs/sdk/configure) `Plandalf.openOffer({ offerId, mode })` - Opens checkout from a page button.
- [Listen for completion](/docs/sdk/events) `Plandalf.on('checkout.completed', handler)` - Routes the completed checkout state back to the page.


### Code explainer

Use this when a snippet needs a short line-by-line reading.

- `offerId: 'offer_123'` - The offer that owns products, prices, layout, and completion behavior.
- `mode: 'modal'` - The checkout opens over the current page instead of replacing it.


### Data-driven switcher

Use this when samples are generated from structured data instead of authored as fenced blocks.

Runs from a sales page or app screen.


```js Browser
await window.Plandalf.openOffer({ offerId: 'offer_123' });
```

Keeps simple pages declarative.


```html HTML
<button data-plandalf-offer='offer_123'>Buy now</button>
```


### Checkout implementation flow

Use VisualFlow for compact implementation paths when a full Mermaid diagram is too formal.

- Add the buying action - Place one button or link on the page.
- [Open the offer](/docs/offers/overview) - Let the offer own checkout layout, products, prices, and redirects.
- [Handle the result](/docs/sdk/events) - React to completion in the browser or backend.

## Audience Targeting

Use `Visibility` and `View` when the web page and Markdown export need different levels of detail.

Mintlify's `Visibility` component is deliberately asymmetric: `for="humans"` renders on the public web page and is excluded from `.md` output, while `for="agents"` is hidden on the web page and included in `.md` output. Use this when the human path is UI-oriented but agents need API-oriented implementation context.

Mintlify-style `View` groups can switch framework-specific content with icons and icon metadata.


### JavaScript

### JavaScript view heading

  JavaScript setup examples can stay on the page while the toolbar exposes the selected view.

  ```js
  console.log("Open a Plandalf offer");
  ```


### Python

### Python view heading

  Python examples can sit beside the same prose without duplicating the whole guide.

  ```python
  print("Open a Plandalf offer")
  ```


### Agent

### Agent view heading

  Package Lucide icons also render in the multi-view toolbar.


### Bare view title

Imported Mintlify view content may rely on the view title instead of adding a duplicate Markdown heading. The `.md` export preserves this wrapper title.


### Agent instruction

Agent-visible content is included in Markdown export and hidden from the public web render.


> You are viewing this content in the Markdown export.
  >
  > Use agent-only visibility for implementation context such as: call `GET /api/offers/{id}` before generating checkout code, preserve the offer ID in examples, and link back to `/docs/offers/overview` when explaining what an offer owns.

## Compatibility Aliases

| Alias | Renders as | Use when |
| --- | --- | --- |
| `Cards` | `CardGroup` | Imported MDX wraps linked cards as a plural collection. |
| `CardGrid` | `CardGroup` | Imported MDX expects a grid wrapper around cards. |
| `Tiles` | `TileGroup` | Imported MDX wraps compact tiles as a plural collection. |
| `TileGrid` | `TileGroup` | Imported MDX expects a grid wrapper around tiles. |
| `Field` | `ParamField` | API docs use a generic field component for request parameters. |
| `Param` | `ParamField` | API docs use short parameter aliases. |
| `Parameter` | `ParamField` | Imported API docs spell out individual request parameters. |
| `ParameterField` | `ParamField` | Imported API docs use the full component name for request parameters. |
| `Property` | `ParamField` | Imported schema docs use property terminology for fields. |
| `Attribute` | `ParamField` | SDK and schema docs use attribute terminology. |
| `RequestField` | `ParamField` | Imported API docs name a single request body, path, query, or header field directly. |
| `RequestParam` | `ParamField` | Imported API docs keep request-specific parameter wording. |
| `RequestParameter` | `ParamField` | Imported API docs spell out a single request parameter. |
| `RequestProperty` | `ParamField` | Imported request-body schema docs use property terminology. |
| `Params` | `Fields` | Imported MDX wraps parameter fields with a short plural name. |
| `ParamFields` | `Fields` | Imported MDX wraps parameter fields with a component-style plural name. |
| `Parameters` | `Fields` | Imported MDX wraps request parameters with the full plural name. |
| `ParameterFields` | `Fields` | Imported API docs wrap parameter fields with the full plural name. |
| `Properties` | `Fields` | Imported schema docs wrap property fields together. |
| `Attributes` | `Fields` | SDK docs group attributes together. |
| `RequestFields` | `Fields` | Imported API docs distinguish request fields from response fields. |
| `RequestParams` | `Fields` | Imported API docs distinguish request parameters from response fields. |
| `RequestParameters` | `Fields` | Imported API docs use the full request parameter wrapper. |
| `RequestProperties` | `Fields` | Imported request-body schema docs group request properties. |
| `ResponseParam` | `ResponseField` | Imported response docs use parameter terminology for returned values. |
| `ResponseProperty` | `ResponseField` | Imported schema docs use property terminology for response rows. |
| `Response` | `Responses` | Response field groups use singular wrapper names. |
| `ResponseFields` | `Responses` | Response field groups use Mintlify-style plural names. |
| `ResponseFieldGroup` | `Responses` | Imported response docs sometimes use an explicit group wrapper. |
| `CodeBlocks` | `CodeGroup` | Imported docs use a plural code wrapper. |
| `CodeBlockGroup` | `CodeGroup` | Imported docs use a grouped code-block wrapper. |
| `CodeGroups` | `CodeGroup` | Imported docs use a plural code wrapper. |
| `CodeTabs` | `CodeGroup` | Imported docs use tab language for equivalent snippets. |
| `AI` | `Prompt` | Prompt-style blocks from imported agent docs render as copyable prompts. |
| `AskAI` | `Prompt` | Prompt-style blocks from imported agent docs render as copyable prompts. |
| `Request` | `RequestExample` | Imported example blocks use short request names. |
| `Requests` | `RequestExample` | Imported example blocks wrap one or more request snippets. |
| `ResponseExampleGroup` | `ResponseExample` | Imported examples expect a named response example wrapper. |
| `Accordions` | `AccordionGroup` | Imported MDX uses the plural wrapper. |
| `Folder` | `TreeFolder` | Tree examples use short names. |
| `File` | `TreeFile` | Tree examples use short names. |
| `Tree.Folder` | `TreeFolder` | Mintlify-style tree examples use compound file nodes. |
| `Tree.File` | `TreeFile` | Mintlify-style tree examples use compound file nodes. |
| `ColorPalette` | `Color` | Imported palette examples avoid compound component syntax. |
| `ColorSwatch` | `ColorItem` | Imported color examples use swatch terminology. |
| `Swatch` | `ColorItem` | Imported color examples use compact swatch names. |
| `PaletteRow` | `ColorRow` | Imported color tables use row wrappers without a compound name. |
| `Color.Item` | `ColorItem` | Mintlify-style color examples use compound swatches. |
| `Color.Row` | `ColorRow` | Mintlify-style color tables use compound rows. |


> **Do not fake product behavior**
>

  Component support only changes the docs rendering layer. Product, SDK, API, webhook, or dashboard claims still need to be verified against the current Plandalf implementation before publishing.