# webmcpui — full documentation

> Framework-agnostic, WebMCP-native web components: accessible form controls an agent can fill and interaction primitives an agent can drive, with Standard Schema validation and design tokens. Each element is a good HTML control first and, when a WebMCP host is present, exposes itself as a tool an agent can call — additive and feature-detected.

Source: https://webmcpui.com


---

# Introduction
URL: https://webmcpui.com/docs

Agent-aware web components for the WebMCP era — framework-agnostic form and interaction primitives with Standard Schema validation.

# Introduction

**webmcpui** is a framework-agnostic, WebMCP-native web component library. Every element is a proper, accessible HTML control first and, when you opt in, also registers an imperative [WebMCP](/docs/webmcp) tool an agent can call.

Three families of primitives:

- **Form controls** expose a *value* an agent can set — `<wmcp-input>`, `<wmcp-textarea>`, `<wmcp-select>`, `<wmcp-checkbox>`, `<wmcp-radio>` / `<wmcp-radio-group>`. Shared behavior (form association, validation, WebMCP exposure, theming) lives in a `WmcpFormControl` base.
- **Interaction primitives** expose an *action* an agent can trigger — `<wmcp-button>`, `<wmcp-dialog>`, `<wmcp-menu>`, `<wmcp-tabs>`, `<wmcp-popover>`, `<wmcp-switch>`, `<wmcp-tooltip>` — or, for `<wmcp-toast>`, a *reading* an agent can perceive. They share a `WmcpAction` / `WmcpExposable` base.
- **Presentational primitives** are accessible, themed controls with no agent surface — `<wmcp-badge>`, `<wmcp-separator>`, `<wmcp-alert>`, `<wmcp-progress>`, `<wmcp-avatar>`.

Building in React or Vue? [`@webmcpui/react`](/docs/frameworks) and [`@webmcpui/vue`](/docs/frameworks) wrap these elements with typed, idiomatic components — same behavior, framework-native ergonomics.

## Why it exists

The same control a person operates by hand, an agent should be able to operate by calling a tool — fill a field, click a button, open a dialog, switch a tab, or read a notification. webmcpui's elements are good, accessible controls first; agent-exposure is additive and opt-in.

It's all feature-detected: with no agent present (the common case today), the WebMCP layer is a complete no-op, so your controls are always good HTML.

## One source of truth, two channels

Vanilla custom elements built with [Lit](https://lit.dev), distributed two ways:

- an **ESM package** for build tools (`@webmcpui/core`), and
- a single-file **CDN bundle** for no-build environments (Webflow, WordPress, plain HTML).

## Next steps

- [Installation](/docs/installation) — add it to your project, with or without a build step.
- [Validation](/docs/validation) — bring any Standard Schema validator.
- [WebMCP exposure](/docs/webmcp) — how elements become agent tools.
- [Testing](/docs/testing) — exercise exposure with the fake agent.


---

# Installation
URL: https://webmcpui.com/docs/installation

Add webmcpui to your project with a build tool, or drop a single script tag — no build step required.

# Installation

Two distribution channels from one source of truth. Use the ESM package with your bundler, or the single-file CDN bundle for no-build environments.

## With a build tool

```bash
pnpm add @webmcpui/core @webmcpui/tokens
```

```ts
import { defineComponents } from '@webmcpui/core';
import '@webmcpui/tokens/css'; // theme tokens (CSS custom properties)

defineComponents(); // registers <wmcp-input> and the other <wmcp-*> elements
```

```html
<wmcp-input label="Email" name="email" type="email"></wmcp-input>
```

Importing the package does **not** register the elements — you call `defineComponents()` so you control timing. (The CDN bundle below registers automatically.)

> In an SSR framework, call `defineComponents()` on the client only — custom elements need the DOM. In Nuxt, for example, do it from a `.client.ts` plugin.

## No build? Drop a script tag

For Webflow, WordPress, or hand-written HTML — one tag, every `<wmcp-*>` element auto-registers:

```html
<link rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@webmcpui/tokens/dist/css/tokens.css" />
<script src="https://cdn.jsdelivr.net/npm/@webmcpui/core/dist/webmcpui.global.js"></script>

<wmcp-input label="Email" name="email" type="email"></wmcp-input>
```

## Frameworks

Because these are standard custom elements, they work anywhere HTML renders. The only framework-specific note is telling the framework's template compiler not to treat `<wmcp-*>` as its own components:

- **Vue / Nuxt** — set `compilerOptions.isCustomElement = (tag) => tag.startsWith('wmcp-')`.
- **React** (19+) — custom elements and their props/attributes work directly.
- **Svelte / SolidJS / Angular** — supported with each framework's standard custom-element handling.


---

# Validation
URL: https://webmcpui.com/docs/validation

Bring any Standard Schema validator — Zod, Valibot, ArkType — and wire it straight into form validation.

# Validation

Every control accepts a [Standard Schema](https://standardschema.dev) validator on its `schema` property. Bring Zod, Valibot, ArkType, or anything that implements the spec — there's no bespoke schema language to learn.

```ts
import { z } from 'zod';

const input = document.querySelector('wmcp-input')!;
input.schema = z.string().email('Enter a valid email');
```

Validation runs on input and during native form validation. On failure the element:

- sets `aria-invalid`,
- renders the error message in a live region (announced to assistive tech), and
- propagates the failure to the containing `<form>` via `ElementInternals`, so native form submission is blocked just like a built-in control.

## Required fields

`required` is a real constraint, not just a visual marker — an empty required control fails validation and participates in native form validity.

```html
<wmcp-input label="Name" name="name" required></wmcp-input>
```

## A note on tool schemas

Standard Schema validates *values* but does not emit JSON Schema, so a control's WebMCP tool parameter schema is derived from the element (its `type`, or its enumerated options for `<wmcp-select>` / `<wmcp-radio-group>`) rather than from the validator. Richer tool schemas are a future enhancement.


---

# WebMCP exposure
URL: https://webmcpui.com/docs/webmcp

How a form control becomes an imperative WebMCP tool an agent can discover and call.

# WebMCP exposure

WebMCP is an imperative browser API — `document.modelContext.registerTool(...)` — that lets a page offer tools to an AI agent running in or alongside the browser. webmcpui controls can register themselves as tools.

## Opt in with `expose`

```html
<wmcp-input label="Email" name="email" type="email" expose></wmcp-input>
<!-- registers a "fill_email" tool an agent can call -->
```

On connect, the element registers an imperative WebMCP tool; on disconnect, it unregisters. It is **feature-detected** — a complete no-op when no agent/host is present (the common case today), so the control is always a good form control first.

## The generated tool

For the example above, the registered tool is:

| Field | Value |
| --- | --- |
| `name` | `fill_email` (`fill_` + the `name` attribute) |
| `description` | `Set the value of the "Email" field.` |
| `inputSchema` | `{ type: 'object', properties: { value: { type: 'string' } }, required: ['value'] }` |

When the agent calls the tool, the element applies the value exactly as if a user typed it — updating state, running validation, announcing errors, and firing `input`/`change` events.

## Customizing the tool

```html
<wmcp-input
  name="email"
  label="Work email"
  expose
  tool-name="set_work_email"
  tool-description="Set the customer's work email address."
></wmcp-input>
```

- `tool-name` overrides the generated `fill_<name>`.
- `tool-description` overrides the generated description.

Controls with enumerated values (`<wmcp-select>`, `<wmcp-radio-group>`) generate an `enum`-typed schema so the agent knows the exact allowed values.

> **Tool names are page-global.** Two `expose`d controls that resolve to the same tool name — say two fields that both become `fill_email` — collide, and the host rejects the duplicate, so the second control won't be agent-callable. webmcpui logs a console warning when it sees this; give one control a unique `name`, or override it with `tool-name`.

## Only on a secure context

WebMCP is a secure-context feature, so `document.modelContext` exists only on **HTTPS** pages — it's `undefined` on plain HTTP (`localhost` counts as secure). webmcpui's feature detection reads that as "no host present" and quietly does nothing, so your controls stay perfectly good form controls. If you're testing exposure on an `http://` staging box and see no tools, that's why.

## Designed for a human in the loop

WebMCP is explicitly a **human-in-the-loop** API — its own goals call out cooperative workflows where a person delegates to an agent while keeping visibility and control, and rule out fully autonomous, headless operation. There is, as yet, **no built-in confirmation or user-prompting primitive** in `registerTool` (it's an [open question](https://github.com/webmachinelearning/webmcp/issues/165)). So consent stays a UI decision you make: an agent can *set* a value or *open* a [dialog](/docs/elements/dialog), but the consequential step — submitting, confirming — remains a deliberate human action. That's the line webmcpui draws by default.

## Imperative and declarative

The API webmcpui builds on is the **imperative** one (`registerTool`). A **declarative** companion is also being standardized: native attributes (`toolname`, `tooldescription`, `toolparamdescription`, `toolautosubmit`) that annotate a plain `<form>` directly. The two describe the same kind of tool; webmcpui uses the imperative path under the hood because it's the lower-level primitive and the only one that covers interaction beyond forms — a [button](/docs/elements/button)'s click or a dialog's open aren't expressible as form annotations.

## Spec status

As of mid-2026 WebMCP is early but moving: a **public origin trial in Chrome 149+**, with Gemini in Chrome as the first consumer. The surface still shifts month to month — it moved to `document.modelContext` (with `navigator.modelContext` deprecated in Chrome 150), and is `undefined` for almost everyone else. Everything here is additive and feature-detected, so adopting webmcpui costs nothing today and pays off as hosts ship. webmcpui detects both surfaces and prefers `document.modelContext`. To exercise exposure now, use the [fake agent](/docs/testing).


---

# Testing
URL: https://webmcpui.com/docs/testing

Exercise WebMCP exposure end-to-end with the bundled fake agent.

# Testing with the fake agent

No mainstream agent calls WebMCP yet, so `@webmcpui/core/testing` ships a fake host that lets you exercise exposure end to end. It installs a stub `navigator.modelContext`, records the tools your elements register, and lets you invoke them exactly as an agent would.

```ts
import { installFakeAgent } from '@webmcpui/core/testing';

const agent = installFakeAgent();

// ... connect a <wmcp-input name="email" expose> to the DOM ...

const result = await agent.call('fill_email', { value: 'ada@webmcpui.com' });
// the live element is now filled, validated, and has fired input/change

agent.restore(); // remove the stub
```

> **Order matters.** Install the fake agent *before* the element connects — controls register their tool in `connectedCallback`, so the host must already be present.

## The handle

`installFakeAgent()` returns:

| Member | Description |
| --- | --- |
| `tools` | All currently-registered tools, in registration order. |
| `get(name)` | Look up a registered tool by name. |
| `call(name, args?)` | Invoke a tool as an agent would; throws if unknown. |
| `restore()` | Restore the previous `navigator.modelContext`. |

This is exactly what powers the live demo on the [homepage](/) — the same fake host, driving real elements.


---

# React & Vue
URL: https://webmcpui.com/docs/frameworks

Idiomatic, typed React and Vue components that wrap the core custom elements — with unstyled and SSR guidance.

# React & Vue

The core is framework-agnostic custom elements — they work in any framework as-is. But `@webmcpui/react` and `@webmcpui/vue` give you **idiomatic, typed** components: real props, `ref`s / `v-model`, and `on*` / `@event` handlers. They're thin wrappers — the WebMCP exposure, form association, and accessibility all live once in [`@webmcpui/core`](/docs), so there's no second implementation to drift.

## React

```bash
pnpm add @webmcpui/react @webmcpui/core react react-dom
```

```tsx
import { Button, Input, Dialog } from '@webmcpui/react';
import '@webmcpui/tokens/css';

function Example() {
  const [email, setEmail] = React.useState('');
  return (
    <>
      <Input label="Email" type="email" value={email}
             onInput={(e) => setEmail(e.currentTarget.value)} expose />
      <Button variant="primary" onClick={save}>Save</Button>
    </>
  );
}
```

Props mirror the [element attributes](/docs/elements/input), camelCased. Imperative handles come through the `ref` (e.g. `dialogRef.current.show()`).

## Vue

```bash
pnpm add @webmcpui/vue @webmcpui/core vue
```

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Button, Input, Dialog } from '@webmcpui/vue';
import '@webmcpui/tokens/css';

const email = ref('');
const open = ref(false);
</script>

<template>
  <Input v-model="email" label="Email" type="email" expose />
  <Button variant="primary" @click="open = true">Book</Button>
  <Dialog v-model:open="open" label="Confirm">…</Dialog>
</template>
```

`v-model` binds an `Input`'s value; `v-model:open` a `Dialog`; `v-model:active` a `Tabs`. **No `isCustomElement` config needed** — the `wmcp-*` tag only lives inside each component's render function, never your templates.

## Unstyled (bring your own styles)

Every layer is headless underneath: the elements render with neutral inline fallbacks and only *look* shadcn-aligned when you load the theme. So:

- **Themed** — `import '@webmcpui/tokens/css'` once at your app root.
- **Unstyled** — don't import it. Then style the elements yourself via the CSS custom properties (e.g. `--button-primary-bg`) or the `::part()` selectors each element exposes:

```css
wmcp-button::part(control) { border-radius: 9999px; }
```

## Server rendering (Next.js, Nuxt, …)

These are **client-rendered custom elements** — importing them evaluates `class extends HTMLElement`, which has no meaning on the server. Load them client-side:

```tsx
// Next.js App Router
'use client';
import dynamic from 'next/dynamic';
const Button = dynamic(() => import('@webmcpui/react').then((m) => m.Button), {
  ssr: false,
});
```

`'use client'` alone isn't enough — Next still renders client components on the server, so use `ssr: false` (or add a DOM shim like [`@lit-labs/ssr-dom-shim`](https://www.npmjs.com/package/@lit-labs/ssr-dom-shim) to render them server-side). In **Nuxt**, register/use them in a `.client` plugin or wrap usage in `<ClientOnly>`. The elements upgrade and hydrate on the client normally.


---

# <wmcp-input>
URL: https://webmcpui.com/docs/elements/input

A text input — the canonical form control, with type variants, validation, and WebMCP exposure.

# `<wmcp-input>`

A single-line text input. The reference implementation of `WmcpFormControl`.

```html
<wmcp-input label="Email" name="email" type="email" helper-text="We'll never share it."></wmcp-input>
```

## Element attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `type` | `string` | Native input type: `text`, `email`, `url`, `tel`, `password`, `number`, `search`. |

## Common attributes

These are shared by every `<wmcp-*>` form control:

| Attribute | Type | Description |
| --- | --- | --- |
| `label` | `string` | Visible label, associated with the control. |
| `name` | `string` | Form field name; also the default tool name (`fill_<name>`). |
| `value` | `string` | Current value. |
| `placeholder` | `string` | Placeholder text. |
| `required` | `boolean` | Real constraint — empty fails validation. |
| `disabled` | `boolean` | Disables the control. |
| `helper-text` | `string` | Helper text below the control. |
| `required-message` | `string` | Custom message when a required field is empty. |
| `expose` | `boolean` | Register a [WebMCP tool](/docs/webmcp) for this control. |
| `tool-name` | `string` | Override the generated tool name. |
| `tool-description` | `string` | Override the generated tool description. |

`schema` (a [Standard Schema](/docs/validation) validator) is set as a **property**, not an attribute:

```ts
import { z } from 'zod';
document.querySelector('wmcp-input')!.schema = z.string().email();
```


---

# <wmcp-textarea>
URL: https://webmcpui.com/docs/elements/textarea

A multi-line text control with the same validation and WebMCP exposure as the input.

# `<wmcp-textarea>`

A multi-line text control. Shares every [common attribute](/docs/elements/input#common-attributes) with `<wmcp-input>`.

```html
<wmcp-textarea
  label="Message"
  name="message"
  rows="5"
  helper-text="Tell us what you need."
></wmcp-textarea>
```

## Element attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `number` | `3` | Visible rows of text. |

The exposed WebMCP tool is `fill_<name>` with a single string `value` argument, identical to `<wmcp-input>`.


---

# <wmcp-select>
URL: https://webmcpui.com/docs/elements/select

A native select with declarative options and an enum-typed WebMCP tool schema.

# `<wmcp-select>`

A dropdown built on the native `<select>` (so you get native keyboard and mobile pickers for free). Shares every [common attribute](/docs/elements/input#common-attributes).

## Declarative options

```html
<wmcp-select label="Country" name="country">
  <option value="us">United States</option>
  <option value="ca">Canada</option>
  <option value="mx">Mexico</option>
</wmcp-select>
```

Option groups are supported with `<optgroup>`.

## Programmatic options

Set the `options` property (an array) for dynamic data:

```ts
const select = document.querySelector('wmcp-select')!;
select.options = [
  { value: 'us', label: 'United States' },
  { value: 'ca', label: 'Canada' },
  { label: 'Europe', options: [{ value: 'fr', label: 'France' }] }, // group
];
```

## Enum-typed tool

When exposed, `<wmcp-select>` generates an `enum`-typed input schema from its options, so an agent is told the exact set of allowed values:

```json
{
  "type": "object",
  "properties": { "value": { "type": "string", "enum": ["us", "ca", "mx"] } },
  "required": ["value"]
}
```


---

# <wmcp-checkbox>
URL: https://webmcpui.com/docs/elements/checkbox

A boolean control whose WebMCP tool takes a checked argument.

# `<wmcp-checkbox>`

A single boolean control. Shares the [common attributes](/docs/elements/input#common-attributes), with a boolean value instead of a string.

```html
<wmcp-checkbox
  label="Subscribe to the newsletter"
  name="subscribe"
  required-message="Please confirm to continue"
></wmcp-checkbox>
```

## Element attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | `false` | Whether the box is checked (reflected). |

## Tool shape

The exposed tool takes a `checked` boolean rather than a string `value`:

```json
{
  "type": "object",
  "properties": { "checked": { "type": "boolean" } },
  "required": ["checked"]
}
```

A `required` checkbox must be checked to pass validation — useful for consent and terms-of-service boxes.


---

# <wmcp-radio-group>
URL: https://webmcpui.com/docs/elements/radio

An accessible radio group with roving focus and an enum-typed WebMCP tool.

# `<wmcp-radio-group>`

A single-choice group. The group is the form-associated control (`<wmcp-radio-group>`); each option is a `<wmcp-radio>`. Roving tabindex and arrow-key navigation work out of the box. Shares the [common attributes](/docs/elements/input#common-attributes).

## Declarative options

```html
<wmcp-radio-group label="Plan" name="plan">
  <wmcp-radio value="free">Free</wmcp-radio>
  <wmcp-radio value="pro">Pro</wmcp-radio>
  <wmcp-radio value="team">Team</wmcp-radio>
</wmcp-radio-group>
```

## Programmatic options

```ts
const group = document.querySelector('wmcp-radio-group')!;
group.options = [
  { value: 'free', label: 'Free' },
  { value: 'pro', label: 'Pro' },
  { value: 'team', label: 'Team' },
];
```

## Enum-typed tool

Like `<wmcp-select>`, an exposed radio group generates an `enum`-typed schema so the agent knows the exact allowed values:

```json
{
  "type": "object",
  "properties": { "value": { "type": "string", "enum": ["free", "pro", "team"] } },
  "required": ["value"]
}
```


---

# <wmcp-button>
URL: https://webmcpui.com/docs/elements/button

A themeable button that exposes an action — not a value — for an agent to trigger.

# `<wmcp-button>`

The first **interaction primitive**. Where the form controls expose a *value* an agent can set, a button exposes an *action* an agent can trigger. With no agent present (the common case today) it is simply a good, accessible button.

```html
<wmcp-button variant="primary">Save</wmcp-button>
```

::button-demo
::

Both a real click and an agent's tool call route through the same inner button, so the click handlers you already wrote run either way — and `type="submit"` / `type="reset"` drive the surrounding form. A `disabled` button can be activated by neither.

## Element attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `string` | `primary` | Visual style: `primary`, `secondary`, `destructive`, `outline`, `ghost` (reflected). |
| `size` | `string` | `md` | `sm`, `md`, or `lg` (reflected). |
| `type` | `string` | `button` | `button`, `submit`, or `reset`. `submit`/`reset` act on the containing form. |
| `disabled` | `boolean` | `false` | Disables the button for humans and agents alike (reflected). |
| `label` | `string` | — | Accessible name. Falls back to the slotted text; set it for icon-only buttons. |
| `name` | `string` | — | Identifier used for the default tool name (`click_<name>`). |
| `expose` | `boolean` | `false` | Register a [WebMCP tool](/docs/webmcp) that activates this button. |
| `tool-name` | `string` | — | Override the generated tool name. |
| `tool-description` | `string` | — | Override the generated tool description. |

The visible label is provided as the element's content (slotted), not via an attribute:

```html
<wmcp-button variant="destructive">Delete account</wmcp-button>
```

## Form participation

A native `<button type="submit">` inside a shadow root can't reach the page's form. `<wmcp-button>` is form-associated, so it does — submitting and resetting work as you'd expect:

```html
<form>
  <wmcp-input name="email" type="email" required></wmcp-input>
  <wmcp-button type="submit">Sign up</wmcp-button>
  <wmcp-button type="reset" variant="ghost">Clear</wmcp-button>
</form>
```

## Tool shape

The exposed tool takes **no arguments** — calling it *is* the action:

```json
{
  "type": "object",
  "properties": {}
}
```

When the agent calls it, the button activates exactly as a click would; the tool result reports what happened (and whether a form was submitted or reset). Activating a `disabled` button returns an error result instead.

## Theming

Every visual is a CSS custom property, defaulting through the [design tokens](/docs/installation) to the shadcn base palette. Override per variant:

```css
:root {
  --button-primary-bg: var(--brand);
  --button-primary-text: var(--brand-foreground);
  --button-radius: 9999px; /* pill buttons */
}
```


---

# <wmcp-dialog>
URL: https://webmcpui.com/docs/elements/dialog

A modal dialog whose exposed action is opening — the agent surfaces it, the human confirms.

# `<wmcp-dialog>`

A modal dialog wrapping the native `<dialog>` element — so it inherits the platform's focus trap, top-layer stacking, backdrop, and Escape-to-close for free. The exposed **action is _open_**: an agent can surface the dialog for the user to review, but closing and confirming stay a deliberate human step.

That asymmetry is the point. An agent can ask for attention; the irreversible confirm is the person's to make. It's the same consent gate the form controls draw between *setting* a value and *submitting* it.

```html
<wmcp-dialog name="booking" label="Confirm booking" expose>
  <h3>Confirm your booking</h3>
  <p>Book Tuesday, 3:00 PM with Dr. Reyes?</p>
  <wmcp-button variant="ghost" onclick="this.closest('wmcp-dialog').close()">Cancel</wmcp-button>
  <wmcp-button variant="primary">Confirm</wmcp-button>
</wmcp-dialog>
```

::dialog-demo
::

## Element attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the dialog is open (reflected — drives `[open]` styling). |
| `modal` | `boolean` | `true` | Open as a focus-trapping modal with a backdrop. Set `false` for a non-modal dialog. |
| `static-backdrop` | `boolean` | `false` | Keep the dialog open when the backdrop is clicked. |
| `label` | `string` | — | Accessible name for the dialog, and the noun in the default tool description. |
| `name` | `string` | — | Identifier used for the default tool name (`open_<name>`). |
| `expose` | `boolean` | `false` | Register a [WebMCP tool](/docs/webmcp) that opens this dialog. |
| `tool-name` | `string` | — | Override the generated tool name. |
| `tool-description` | `string` | — | Override the generated tool description. |

## Methods, events & properties

| Member | Kind | Description |
| --- | --- | --- |
| `show()` | method | Open the dialog (modal unless `modal` is `false`). |
| `close(returnValue?)` | method | Close it, optionally recording a `returnValue`. |
| `returnValue` | property | The value the dialog last closed with (mirrors native `<dialog>`). |
| `open` event | event | Fired (composed) when the dialog opens. |
| `close` event | event | Fired (composed) when it closes — via `close()`, Escape, or backdrop. |

## Tool shape

Like every [interaction primitive](/docs/elements/button), the exposed tool takes **no arguments** — calling it opens the dialog:

```json
{
  "type": "object",
  "properties": {}
}
```

Calling the tool on an already-open dialog is a no-op that reports as much; it never closes the dialog (closing is never the agent's call).

## Theming

Every visual is a CSS custom property defaulting through the [design tokens](/docs/installation) to the shadcn popover palette, including the backdrop:

```css
:root {
  --dialog-bg: var(--popover);
  --dialog-radius: 1rem;
  --dialog-backdrop: color-mix(in oklch, black 60%, transparent);
}
```

The entrance fade-and-lift uses `@starting-style` and `transition-behavior: allow-discrete`, and is suppressed under `prefers-reduced-motion`.


---

# <wmcp-menu>
URL: https://webmcpui.com/docs/elements/menu

A menu button whose exposed action is parameterized — the agent picks which item.

# `<wmcp-menu>`

A menu button. Its exposed action is the first **parameterized** one in the library: where [button](/docs/elements/button) and [dialog](/docs/elements/dialog) expose no-argument actions, the menu's tool takes *which item* — an `enum` of the item values — so the agent picks exactly as a person would.

The popup uses the native Popover API (top layer, light-dismiss, Escape, and anchored positioning), with arrow-key roving focus over the items. Selecting one — by click, keyboard, or agent — fires a composed `select` event and closes the menu. A menu **dispatches actions; it does not hold a value.**

```html
<wmcp-menu name="row_action" label="Row actions" expose>
  <option value="duplicate">Duplicate</option>
  <option value="archive">Archive</option>
  <option value="delete">Delete</option>
</wmcp-menu>
```

::menu-demo
::

## Items

Items come from declarative `<option>` children — the same authoring as [`<wmcp-select>`](/docs/elements/select), works with no build — or from the `items` property for JS / framework callers:

```ts
document.querySelector('wmcp-menu').items = [
  { value: 'duplicate', label: 'Duplicate' },
  { value: 'delete', label: 'Delete', disabled: true },
];
```

When `items` is non-empty it takes precedence over the children. Disabled items render but can't be selected, and are left out of the tool's `enum`.

## Element attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | Trigger text and the menu's accessible name. |
| `items` | `WmcpMenuItem[]` | `[]` | Items as data (property only); overrides `<option>` children. |
| `open` | `boolean` | `false` | Whether the popup is open (reflected; driven by the trigger). |
| `name` | `string` | — | Identifier used for the default tool name (`select_<name>`). |
| `expose` | `boolean` | `false` | Register a [WebMCP tool](/docs/webmcp) that selects an item. |
| `tool-name` | `string` | — | Override the generated tool name. |
| `tool-description` | `string` | — | Override the generated tool description. |

Selecting fires `select` with `detail: { value, label }`.

## Tool shape

The tool takes one argument — the item to pick, constrained to the enabled values:

```json
{
  "type": "object",
  "properties": {
    "item": { "type": "string", "enum": ["duplicate", "archive", "delete"] }
  },
  "required": ["item"]
}
```

The `enum` tracks the live item set: change `items` and the tool re-registers with the new values. Selecting an unknown or disabled item returns an error result.

## Theming

Trigger and popup are themed through `--menu-*` custom properties, defaulting to the shadcn palette:

```css
:root {
  --menu-bg: var(--popover);
  --menu-item-bg-hover: var(--accent);
  --menu-radius: 0.75rem;
}
```


---

# <wmcp-tabs>
URL: https://webmcpui.com/docs/elements/tabs

A tab set whose exposed action switches a persistent active tab — the first stateful interaction primitive.

# `<wmcp-tabs>`

A tab set — and the first **stateful** interaction primitive. Where [button](/docs/elements/button), [dialog](/docs/elements/dialog), and [menu](/docs/elements/menu) dispatch one-shot actions, a tab set holds a persistent `active` selection (reflected as an attribute), and the agent's tool both reads it and moves it. Switching — by click, arrow keys, or agent — reveals the matching panel and fires a composed `change` event.

```html
<wmcp-tabs name="account" label="Account" active="overview" expose>
  <section tab="overview" tab-label="Overview">Your account at a glance.</section>
  <section tab="usage" tab-label="Usage">12,480 requests this month.</section>
  <section tab="billing" tab-label="Billing">Pro plan · renews Jul 28.</section>
</wmcp-tabs>
```

::tabs-demo
::

## Panels

Panels are declarative light-DOM children carrying a `tab` attribute; the tablist is derived from them. Each panel takes an optional `tab-label` (falling back to the `tab` value) and `tab-disabled`:

| Panel attribute | Description |
| --- | --- |
| `tab` | The tab's value — used in `active`, the `change` event, and the tool enum. |
| `tab-label` | The visible tab label (defaults to the `tab` value). |
| `tab-disabled` | Renders the tab but blocks selection; excluded from the tool enum. |

The active panel is shown; the rest get `hidden`. Keyboard follows the ARIA tabs pattern — arrow keys (with Home/End) move the active tab and focus.

## Element attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `string` | first tab | The value of the active tab (reflected — the persistent state). |
| `label` | `string` | — | Accessible name for the tablist, and the noun in the tool description. |
| `name` | `string` | — | Identifier used for the default tool name (`switch_<name>`). |
| `expose` | `boolean` | `false` | Register a [WebMCP tool](/docs/webmcp) that switches the active tab. |
| `tool-name` | `string` | — | Override the generated tool name. |
| `tool-description` | `string` | — | Override the generated tool description. |

Switching fires `change` with `detail: { value }`.

## Tool shape

The tool takes the tab to switch to, constrained to the enabled values:

```json
{
  "type": "object",
  "properties": {
    "tab": { "type": "string", "enum": ["overview", "usage", "billing"] }
  },
  "required": ["tab"]
}
```

The `enum` tracks the live tabs, and the result reports which tab is now active — so an agent can read the state it just set. Switching to an unknown or disabled tab returns an error result.

## Theming

Tablist, tabs, and the active indicator are themed through `--tabs-*` custom properties:

```css
:root {
  --tabs-indicator: var(--brand);
  --tabs-tab-text-active: var(--foreground);
}
```


---

# <wmcp-popover>
URL: https://webmcpui.com/docs/elements/popover

A non-modal anchored floating panel — and a tooltip mode — whose exposed action is opening.

# `<wmcp-popover>`

A non-modal, anchored floating panel — the sibling of the [dialog](/docs/elements/dialog) (modal) and the [menu](/docs/elements/menu) (action list). It uses the same native Popover API + CSS anchor positioning as the menu (top layer, light-dismiss, Escape), but its content is arbitrary. The exposed action is **open**: the agent surfaces the panel, and closing stays a light-dismiss or human step — the same consent posture as the dialog.

```html
<wmcp-popover name="account_menu" label="Account ▾" expose>
  <p>Signed in as Ada</p>
</wmcp-popover>
```

::popover-demo
::

## Click vs hover (tooltip)

`trigger="click"` (the default) is an interactive popover — click to toggle, light-dismiss to close. `trigger="hover"` turns it into a **tooltip**: it opens on hover and focus, closes on leave and blur, gets `role="tooltip"`, and labels its trigger via `aria-describedby`.

```html
<!-- tooltip -->
<wmcp-popover trigger="hover" label="Copy to clipboard">
  <button slot="trigger" aria-label="Copy">⧉</button>
  Copy to clipboard
</wmcp-popover>
```

The trigger content comes from the `trigger` slot (falling back to `label`); the panel content is the default slot.

## Element attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the panel is open (reflected). |
| `placement` | `string` | `bottom` | `top`, `bottom`, `left`, or `right` of the trigger. |
| `trigger` | `string` | `click` | `click` (interactive popover) or `hover` (tooltip). |
| `label` | `string` | — | Trigger text (when no `trigger` slot) and the panel's accessible name. |
| `name` | `string` | — | Identifier used for the default tool name (`open_<name>`). |
| `expose` | `boolean` | `false` | Register a [WebMCP tool](/docs/webmcp) that opens the panel. |
| `tool-name` | `string` | — | Override the generated tool name. |
| `tool-description` | `string` | — | Override the generated tool description. |

`show()` / `close()` methods and composed `open` / `close` events round out the imperative surface.

## Tool shape

Like the dialog, the exposed tool takes **no arguments** — calling it opens the panel:

```json
{ "type": "object", "properties": {} }
```

Opening an already-open popover is a no-op that reports as much; the tool never closes it.

## Theming

The panel is themed through `--popover-*` custom properties (shadcn popover palette), and the trigger is unstyled by default so any content sits flush — theme it via `::part(trigger)`:

```css
:root {
  --popover-bg: var(--popover);
  --popover-max-width: 22rem;
}
wmcp-popover::part(trigger) { font-weight: 500; }
```


---

# <wmcp-toast>
URL: https://webmcpui.com/docs/elements/toast

A notification region whose agent surface is perceiving, not actuating — the agent reads the toasts the page throws.

# `<wmcp-toast>`

A notification region — and the one component whose agent surface is **perceiving**, not actuating. Page code throws toasts the way it always has, and they announce to screen readers via an `aria-live` region. When `expose` is set, those very same notifications become readable by an agent through a `read_<name>` tool: the machine-readable twin of the `aria-live` announcement.

That's the right shape because the agent's job isn't to *post* toasts — it has its own channel for that — it's to *notice* them. A toast is often the only signal of an outcome ("Payment declined", an async "Export ready"), so an agent acting on the user's behalf reads the toasts rather than creating them. It extends `WmcpExposable` directly, not the action base, because the tool reports state instead of triggering anything.

```html
<wmcp-toast name="notifications" expose></wmcp-toast>
```

```ts
// Page code throws toasts as usual:
document.querySelector('wmcp-toast').show({
  message: 'Payment received',
  variant: 'success',
});
```

::toast-demo
::

## The primitive

`show(options)` returns an id; `dismiss(id)` and `clear()` remove toasts. Each is an `aria-live` child (`role="status"`, or `role="alert"` for `error`), so screen readers announce it.

| `show()` option | Type | Description |
| --- | --- | --- |
| `message` | `string` | The notification text (required). |
| `title` | `string` | Optional bold heading above the message. |
| `variant` | `string` | `info`, `success`, `warning`, or `error` (styling + the read summary). |
| `duration` | `number` | Auto-dismiss after this many ms; `0` keeps it until dismissed. |

## Element attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `string` | `bottom-right` | Corner the toasts stack in (`bottom-right`, `bottom-left`, `top-right`, `top-left`). |
| `duration` | `number` | `5000` | Default auto-dismiss for `show()` calls without their own. |
| `name` | `string` | — | Identifier for the default tool name (`read_<name>`, else `read_notifications`). |
| `expose` | `boolean` | `false` | Register the [WebMCP](/docs/webmcp) read tool. |
| `tool-name` / `tool-description` | `string` | — | Override the generated tool name / description. |

## Tool shape

A no-argument **read** tool:

```json
{ "type": "object", "properties": {} }
```

Calling it returns the notifications currently shown — and, if none are, the ones that appeared in the last 30 seconds — so an agent that checks *after* an async toast has auto-dismissed still learns what happened.

## Theming

Themed through `--toast-*` custom properties, including per-variant accent colors:

```css
:root {
  --toast-bg: var(--popover);
  --toast-accent-success: oklch(0.627 0.13 160);
  --toast-inset: 1.5rem;
}
```