# Examples
Use request, response, and generic examples to keep copyable code beside the endpoint or concept a reader is viewing.
Source: /docs/components/examples
Last modified: 2026-06-20
Examples render copyable code blocks with language labels and optional switchers. On API pages, `RequestExample` and `ResponseExample` clone into the desktop right rail and switch as the active endpoint changes.


> **Use the right example type**
>

  Use `RequestExample` for a call the reader sends, `ResponseExample` for what comes back, and `Example` for non-API snippets that should stay inline.


> **Keep side-panel examples together**
>

  If a page uses a right-rail `Panel`, put the request and response examples inside that panel. If the page documents API calls, use `ApiEndpoint` so examples stay tied to the active endpoint.


## Request and response


### Create a session


```bash title="POST /api/checkout/sessions"
curl -X POST "https://api.plandalf.com/api/checkout/sessions" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"offer":"pro-plan"}'
```

```js title="create-session.js"
const response = await fetch("https://api.plandalf.com/api/checkout/sessions", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify({ offer: "pro-plan" })
});
```


### Session response


```json title="201 checkout session"
{
  "session": {
    "id": "cs_123",
    "status": "open"
  }
}
```


````mdx title="examples.mdx"

### Create a session


  ```bash title="POST /api/checkout/sessions"
  curl -X POST "https://api.plandalf.com/api/checkout/sessions"
  ```

  ```js title="create-session.js"
  await fetch("https://api.plandalf.com/api/checkout/sessions", { method: "POST" });
  ```


### Session response


  ```json title="201 checkout session"
  { "session": { "id": "cs_123", "status": "open" } }
  ```


````

## Generic examples

Use `Example` for short code that is not an API request or response. It still gets language labels, copy controls, and optional dropdown behavior.


### Declarative button


```html title="button.html"
<button
  data-plandalf-offer="pro-plan"
  data-plandalf-mode="modal"
>
  Buy now
</button>
```

```jsx title="BuyButton.jsx"
export function BuyButton() {
  return (
    <button onClick={() => plandalf.openOffer({ offerId: "pro-plan" })}>
      Buy now
    </button>
  );
}
```


## Dropdown examples

Use `dropdown` when there are too many languages for a horizontal tab row.


### Install SDK


```bash title="npm"
npm install @plandalf/js
```

```bash title="pnpm"
pnpm add @plandalf/js
```

```bash title="yarn"
yarn add @plandalf/js
```


## Right-rail patterns


### Where examples belong


- `Inside ApiEndpoint` (API reference):
    Use this for endpoint pages. The request and response examples clone into the API rail and switch with the active call.


- `Inside Panel` (side context):
    Use this when a guide needs a pinned sidebar sample but is not primarily an endpoint reference.


- `Inline with rail={false}` (component docs):
    Use this in component reference pages so the example appears exactly where it is being explained.


## Properties

Both `RequestExample` and `ResponseExample` accept this Mintlify property.


- `dropdown` (boolean; default: false):
  Display a dropdown menu for switching between code blocks instead of the default tab layout.


## Plandalf extensions


- `title` (string):
  Heading for the example block.


- `labels` (string[]):
  Labels multiple fenced code blocks when the code titles are not enough.


- `rail` (boolean; default: true):
  Controls whether request and response examples clone into the API right rail.


- `type` (request | response | example; default: example):
  `RequestExample` and `ResponseExample` set this automatically. Use `Example` directly for non-API snippets.


- `status` (string | number):
  Adds an HTTP status badge to response examples and response variant controls in the API rail.


- `statusText` (string):
  Adds the human-readable HTTP status text for response examples.


## Authoring rules

- Put request and response examples inside the same `ApiEndpoint` as their fields.
- Use equivalent snippets when multiple languages appear in one example.
- Keep response examples realistic and small enough to scan in the right rail.
- Set `rail={false}` on component docs pages so examples stay inline.
- Use `CodeGroup` when the code is the main content, and `Example` when the snippet supports a field or endpoint.

## Related components


  - [Fields](/docs/components/fields): Document request shape first.
  - [API examples guide](/docs/components/api-fields-examples): See full endpoint examples.
  - [Developer API reference](/docs/api/reference): See active right-rail examples.