---
title: Show Toast
description: Display a notification from any UI interaction.
icon: bell
---

import { ComponentPreview } from '/snippets/component-preview.mdx'

`ShowToast` displays a brief notification. It's a client-side action — no server round-trip — so feedback is instant. Fire it directly from a button click, or use it as a `CallTool` callback to report success or failure after a server action completes.

<ComponentPreview json={{"view":{"cssClass":"gap-2","type":"Row","children":[{"type":"Button","label":"Notify","variant":"default","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Something happened"}},{"type":"Button","label":"Warn me","variant":"outline","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Improbability levels rising","variant":"warning"}}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQnV0dG9uLCBSb3cKZnJvbSBwcmVmYWJfdWkuYWN0aW9ucyBpbXBvcnQgU2hvd1RvYXN0Cgp3aXRoIFJvdyhnYXA9Mik6CiAgICBCdXR0b24oIk5vdGlmeSIsIG9uX2NsaWNrPVNob3dUb2FzdCgiU29tZXRoaW5nIGhhcHBlbmVkIikpCiAgICBCdXR0b24oIldhcm4gbWUiLCB2YXJpYW50PSJvdXRsaW5lIiwKICAgICAgICAgICBvbl9jbGljaz1TaG93VG9hc3QoIkltcHJvYmFiaWxpdHkgbGV2ZWxzIHJpc2luZyIsIHZhcmlhbnQ9Indhcm5pbmciKSkK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Button, Row
from prefab_ui.actions import ShowToast

with Row(gap=2):
    Button("Notify", on_click=ShowToast("Something happened"))
    Button("Warn me", variant="outline",
           on_click=ShowToast("Improbability levels rising", variant="warning"))
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-2",
    "type": "Row",
    "children": [
      {
        "type": "Button",
        "label": "Notify",
        "variant": "default",
        "size": "default",
        "disabled": false,
        "onClick": {"action": "showToast", "message": "Something happened"}
      },
      {
        "type": "Button",
        "label": "Warn me",
        "variant": "outline",
        "size": "default",
        "disabled": false,
        "onClick": {
          "action": "showToast",
          "message": "Improbability levels rising",
          "variant": "warning"
        }
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Variants

The `variant` parameter controls the toast's visual style. Omit it for a neutral default.

<ComponentPreview json={{"view":{"cssClass":"gap-2 flex-wrap","type":"Row","children":[{"type":"Button","label":"Default","variant":"outline","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Something happened"}},{"type":"Button","label":"Success","variant":"success","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Towel registered","variant":"success"}},{"type":"Button","label":"Error","variant":"destructive","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Towel not found","variant":"error"}},{"type":"Button","label":"Warning","variant":"warning","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Improbability drive unstable","variant":"warning"}},{"type":"Button","label":"Info","variant":"info","size":"default","disabled":false,"onClick":{"action":"showToast","message":"42 towels in inventory","variant":"info"}}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Button, Row
from prefab_ui.actions import ShowToast

with Row(gap=2, css_class="flex-wrap"):
    Button("Default", variant="outline",
           on_click=ShowToast("Something happened"))
    Button("Success", variant="success",
           on_click=ShowToast("Towel registered", variant="success"))
    Button("Error", variant="destructive",
           on_click=ShowToast("Towel not found", variant="error"))
    Button("Warning", variant="warning",
           on_click=ShowToast("Improbability drive unstable", variant="warning"))
    Button("Info", variant="info",
           on_click=ShowToast("42 towels in inventory", variant="info"))
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-2 flex-wrap",
    "type": "Row",
    "children": [
      {
        "type": "Button",
        "label": "Default",
        "variant": "outline",
        "size": "default",
        "disabled": false,
        "onClick": {"action": "showToast", "message": "Something happened"}
      },
      {
        "type": "Button",
        "label": "Success",
        "variant": "success",
        "size": "default",
        "disabled": false,
        "onClick": {"action": "showToast", "message": "Towel registered", "variant": "success"}
      },
      {
        "type": "Button",
        "label": "Error",
        "variant": "destructive",
        "size": "default",
        "disabled": false,
        "onClick": {"action": "showToast", "message": "Towel not found", "variant": "error"}
      },
      {
        "type": "Button",
        "label": "Warning",
        "variant": "warning",
        "size": "default",
        "disabled": false,
        "onClick": {
          "action": "showToast",
          "message": "Improbability drive unstable",
          "variant": "warning"
        }
      },
      {
        "type": "Button",
        "label": "Info",
        "variant": "info",
        "size": "default",
        "disabled": false,
        "onClick": {"action": "showToast", "message": "42 towels in inventory", "variant": "info"}
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Description Text

Add a secondary line with the `description` parameter for toasts that need more context.

<ComponentPreview json={{"view":{"type":"Button","label":"Deploy","variant":"default","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Deployment complete","description":"3 agents online","variant":"success"}}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQnV0dG9uCmZyb20gcHJlZmFiX3VpLmFjdGlvbnMgaW1wb3J0IFNob3dUb2FzdAoKQnV0dG9uKAogICAgIkRlcGxveSIsCiAgICBvbl9jbGljaz1TaG93VG9hc3QoCiAgICAgICAgIkRlcGxveW1lbnQgY29tcGxldGUiLAogICAgICAgIGRlc2NyaXB0aW9uPSIzIGFnZW50cyBvbmxpbmUiLAogICAgICAgIHZhcmlhbnQ9InN1Y2Nlc3MiLAogICAgKSwKKQo=">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Button
from prefab_ui.actions import ShowToast

Button(
    "Deploy",
    on_click=ShowToast(
        "Deployment complete",
        description="3 agents online",
        variant="success",
    ),
)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "Button",
    "label": "Deploy",
    "variant": "default",
    "size": "default",
    "disabled": false,
    "onClick": {
      "action": "showToast",
      "message": "Deployment complete",
      "description": "3 agents online",
      "variant": "success"
    }
  }
}
```
</CodeGroup>
</ComponentPreview>

## Duration

By default the host decides how long toasts persist. Override with `duration` (in milliseconds):

```python
ShowToast("Quick flash", duration=1500)
ShowToast("Read this carefully", duration=10000)
```

## As CallTool Callbacks

The most common pattern: use `ShowToast` as `on_success` and `on_error` callbacks on a `CallTool` to give feedback after a server action completes.

<ComponentPreview json={{"view":{"cssClass":"gap-2","type":"Row","children":[{"type":"Button","label":"Success callback","variant":"success","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Saved successfully!","variant":"success"}},{"type":"Button","label":"Error callback","variant":"destructive","size":"default","disabled":false,"onClick":{"action":"showToast","message":"Could not save: connection timed out","variant":"error"}}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQnV0dG9uLCBSb3cKZnJvbSBwcmVmYWJfdWkuYWN0aW9ucyBpbXBvcnQgU2hvd1RvYXN0Cgp3aXRoIFJvdyhnYXA9Mik6CiAgICBCdXR0b24oIlN1Y2Nlc3MgY2FsbGJhY2siLCB2YXJpYW50PSJzdWNjZXNzIiwKICAgICAgICAgICBvbl9jbGljaz1TaG93VG9hc3QoIlNhdmVkIHN1Y2Nlc3NmdWxseSEiLCB2YXJpYW50PSJzdWNjZXNzIikpCiAgICBCdXR0b24oIkVycm9yIGNhbGxiYWNrIiwgdmFyaWFudD0iZGVzdHJ1Y3RpdmUiLAogICAgICAgICAgIG9uX2NsaWNrPVNob3dUb2FzdCgiQ291bGQgbm90IHNhdmU6IGNvbm5lY3Rpb24gdGltZWQgb3V0IiwgdmFyaWFudD0iZXJyb3IiKSkK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Button, Row
from prefab_ui.actions import ShowToast

with Row(gap=2):
    Button("Success callback", variant="success",
           on_click=ShowToast("Saved successfully!", variant="success"))
    Button("Error callback", variant="destructive",
           on_click=ShowToast("Could not save: connection timed out", variant="error"))
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-2",
    "type": "Row",
    "children": [
      {
        "type": "Button",
        "label": "Success callback",
        "variant": "success",
        "size": "default",
        "disabled": false,
        "onClick": {"action": "showToast", "message": "Saved successfully!", "variant": "success"}
      },
      {
        "type": "Button",
        "label": "Error callback",
        "variant": "destructive",
        "size": "default",
        "disabled": false,
        "onClick": {
          "action": "showToast",
          "message": "Could not save: connection timed out",
          "variant": "error"
        }
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

Wire these onto a `CallTool` with `on_success` and `on_error`. The `{{ $error }}` variable captures the error message from the server.

```python
from prefab_ui.rx import Rx

item = Rx("item")

Button(
    "Save",
    on_click=CallTool(
        "save_item",
        arguments={"data": item},
        on_success=ShowToast("Saved successfully!", variant="success"),
        on_error=ShowToast("{{ $error }}", variant="error"),
    ),
)
```

## API Reference

<Card icon="code" title="ShowToast Parameters">
<ParamField body="message" type="str" required>
  Toast message text. Can be passed as a positional argument. Supports `{{ key }}` interpolation.
</ParamField>
<ParamField body="description" type="str | None" default="None">
  Optional secondary text displayed below the message.
</ParamField>
<ParamField body="variant" type='"default" | "success" | "error" | "warning" | "info" | None' default="None">
  Visual style of the toast.
</ParamField>
<ParamField body="duration" type="int | None" default="None">
  Auto-dismiss duration in milliseconds. When omitted, the host decides.
</ParamField>
</Card>

## Protocol Reference

```json ShowToast
{
  "action": "showToast",
  "message": "string (required)",
  "description?": "string",
  "variant?": "default | success | error | warning | info",
  "duration?": "number"
}
```

For the complete protocol schema, see [ShowToast](/protocol/show-toast).
