> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Canvas components

> Every card the PAL can show, how to enable and configure them, and the layout and display_mode controls they all share.

**Canvas components** are the cards a PAL can render on the Magic Canvas surface during a conversation. Four are interactive, three display-only:

Magic Canvas adds **Canvas actions** - built-in LLM functions such as `canvas_show_question` - when the skill is attached. These are not the same as [Tools](/sections/conversational-video-interface/pal/tools) you create via the Tools API and attach to a PAL. If a name collides, your Tools API definition wins.

| Component                                                                                               | Description                                                         | Interactive  |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------ |
| [`question`](/sections/conversational-video-interface/magic-canvas/components/question)                 | Ask a multiple-choice question, optionally with a free-text "Other" | Yes          |
| [`input`](/sections/conversational-video-interface/magic-canvas/components/input)                       | Ask for a single typed value: text, email, number, or phone         | Yes          |
| [`calendar`](/sections/conversational-video-interface/magic-canvas/components/calendar)                 | Let the user pick a date, a time slot, or a date range              | Yes          |
| [`scheduling_embed`](/sections/conversational-video-interface/magic-canvas/components/scheduling-embed) | Embed your real scheduling page (e.g. Calendly) for live booking    | Yes          |
| [`text`](/sections/conversational-video-interface/magic-canvas/components/text)                         | Show a card of formatted text                                       | Dismiss only |
| [`chart`](/sections/conversational-video-interface/magic-canvas/components/chart)                       | Show a bar, line, or pie chart                                      | Dismiss only |
| [`alert`](/sections/conversational-video-interface/magic-canvas/components/alert)                       | Show a dismissible notice                                           | Dismiss only |

All components are versioned `v1`.

## Enabling and configuring components

Components come from the PAL's `magic_canvas` skill. Attach it:

```bash theme={null}
curl -X PUT https://tavusapi.com/v2/pals/{pal_id}/skills/magic_canvas \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "config": {} }'
```

Attaching the skill enables **every component** with its defaults. `config.components` is a sparse overlay, not an allowlist; add an entry only to configure or disable:

```json theme={null}
{ "config": { "components": { "chart": { "enabled": false } } } }
```

Overlay rules:

* Per-component `enabled` defaults to `true`.
* `scheduling_embed` stays inactive until `scheduling_url` is set; a bare attach doesn't error.
* Unknown component names and stray fields inside a component entry are rejected with a `400`.

<Note>
  Tavus compiles Canvas actions only for conversations with a rendering surface.
  Audio-only, text-chat, and external `meeting_url` (Zoom, Teams, Meet)
  conversations get no Canvas actions, regardless of PAL configuration.
</Note>

See [Canvas configuration](/sections/conversational-video-interface/magic-canvas/api/configuration) for the full config shape, PATCH/bulk-PUT/DELETE endpoints, and validation errors.

## Control actions

Each active component gives the PAL one `canvas_show_<component>` action. With at least one component active, the PAL also gets two control actions:

| Action             | Description                                                                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `canvas_clear`     | Remove a card by its `tool_call_id`, or clear the whole canvas when no target is given.                                                                                                                      |
| `update_component` | Revise a visible card **in place** (new chart data, reworded text, updated options) without dismissing and re-showing it. The card keeps its `tool_call_id`, so interactions stay tied to the same instance. |

Canvas actions are model-driven, steered by the PAL's system prompt. A Canvas action never overwrites a [tool](/sections/conversational-video-interface/pal/tools) you defined with the same name; your tool wins (see [Canvas configuration](/sections/conversational-video-interface/magic-canvas/api/configuration#how-the-configuration-reaches-a-conversation)).

## Shared `layout` and `display_mode` controls

Every Canvas action accepts two optional shared arguments, placement hints the PAL sets when showing a card:

| Field          | Type   | Values                                                       | Description                                                                             |
| -------------- | ------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `layout`       | object | `preferred_slot`: one of `safe-area-right`, `safe-area-left` | Placement hint. The client may adapt it for viewport, keyboard, and safety constraints. |
| `display_mode` | string | `inline`                                                     | Cards render inline within their slot. `inline` is the only supported value.            |

The PAL can also pass `preferred_slot` at the top level as shorthand for `layout.preferred_slot`. Steer placement from the system prompt, for example "keep cards on the left."

### Default placement

GA renders every card in a side rail (`safe-area-right`), inline, regardless of the component or the hint the PAL passes, so the effective placement is the same for all components:

| Component                                           | Effective slot    |
| --------------------------------------------------- | ----------------- |
| `question`, `input`, `calendar`, `scheduling_embed` | `safe-area-right` |
| `text`, `chart`, `alert`                            | `safe-area-right` |