# Mirio

> Mirio is inbound for sites that coding agents build: the building blocks and automations for demo request, contact, waitlist, onboarding and quote forms, whose every response is screened, read and routed. The form lives in the site's own code: a typed schema file and the `@trymirio/mirio` React components (Next.js, Vite, Astro). Mirio's hosted backend handles everything after submit: validation, spam protection, storage that stays coherent as the form changes, partial saves for multi-step forms, AI triage (a one-line summary, a category and a fit for each response), where each visitor came from, and delivery to email, Slack, signed webhooks or the site's own Postgres. The agent writes the form. Mirio handles everything after submit.

All the docs in one Markdown file: https://trymirio.com/llms-full.txt

Install: `npm install @trymirio/mirio`. CLI: `npx @trymirio/mirio <command>` (or `npx mirio <command>` after install). Everything is reachable without a browser except two one-time steps a human does: claiming the project (a Google, GitHub or email sign-in) and connecting Slack ("Add to Slack").

Pricing: free during the beta, with every feature, up to 1,000 responses a month (https://trymirio.com/docs/limits.md). Site: https://trymirio.com. Questions: https://trymirio.com/contact.

## Get started

- [Quickstart (agent happy path)](https://api.trymirio.com/docs/index.md): `npx @trymirio/mirio init --agent <your name>` (adds the framework plugin and CSS; agents name themselves with `--agent`) → write schema → render form → dev server registers it → test → claim → `mirio env vercel`.
- [When to use Mirio](https://api.trymirio.com/docs/when-to-use.md): what it's for, when another tool fits better, and how it compares to form endpoints and hosted builders.
- [Claiming and the sandbox](https://api.trymirio.com/docs/claiming.md): why unclaimed projects only accept localhost, how to go live.
- [CLI](https://api.trymirio.com/docs/cli.md): `init`, `sync`, `env`, `push`, `test`, `status`, `check`, `claim`, `submissions`, `destinations`, `domains`, `review`, all with `--json`.
- [Changelog](https://api.trymirio.com/docs/changelog.md): what changed in each `@trymirio/mirio` release; read it when you upgrade.

## Build forms

- [Form schema](https://api.trymirio.com/docs/schema.md): `defineForm`, field types, constraints, pages, `renamedFrom`, settings.
- [Conditional logic](https://api.trymirio.com/docs/conditional-logic.md): `showWhen` on fields and pages.
- [Attribution and hidden fields](https://api.trymirio.com/docs/attribution.md): the page that led to the form, the landing page, the site the visit came from, campaign tags; `<MirioAttribution />` in the root layout; hidden fields from URL parameters.
- [Components overview](https://api.trymirio.com/docs/components.md): `<Form>` auto-render, composing fields, multi-step, headless primitives.
- [Styling](https://api.trymirio.com/docs/styling.md): five layers: inherit the site (shadcn mapping), dark mode, tokens and `theme`, `size` and `layout`, `classNames`; Tailwind vs compiled CSS.
- [Theming](https://api.trymirio.com/docs/theming.md): every `theme` key, sizes, `layout`, `classNames` slots, with a live playground.

## Components (one page each: usage, props, customization)

- [Form](https://api.trymirio.com/docs/components/form.md), [Field](https://api.trymirio.com/docs/components/field.md), [Input](https://api.trymirio.com/docs/components/input.md), [Textarea](https://api.trymirio.com/docs/components/textarea.md), [Select](https://api.trymirio.com/docs/components/select.md), [Choice](https://api.trymirio.com/docs/components/choice.md), [YesNo](https://api.trymirio.com/docs/components/yes-no.md), [Rating](https://api.trymirio.com/docs/components/rating.md), [DatePicker](https://api.trymirio.com/docs/components/date-picker.md), [Consent](https://api.trymirio.com/docs/components/consent.md), [Submit](https://api.trymirio.com/docs/components/submit.md), [Success](https://api.trymirio.com/docs/components/success.md), [MultiStep, Page and Progress](https://api.trymirio.com/docs/components/multi-step.md), [Label, Help and FieldError](https://api.trymirio.com/docs/components/label-help-error.md), [MirioProvider](https://api.trymirio.com/docs/components/provider.md), [Headless hooks](https://api.trymirio.com/docs/components/headless.md)

## After submit

- [Spam and validation](https://api.trymirio.com/docs/spam.md): what the server checks, what gets flagged, Cloudflare Turnstile with your own widget (`npx mirio turnstile set <secret key>`), what is never dropped.
- [Enrichment](https://api.trymirio.com/docs/enrichment.md): email signals, duplicates, velocity, company domain.
- [Triage (AI review)](https://api.trymirio.com/docs/ai-review.md): summary, category, fit against the form's ideal response (`npx mirio review <slug> --ideal "…"`), stated facts and a spam second opinion per response; corrections; privacy.
- [Partial submissions](https://api.trymirio.com/docs/partials.md): how multi-step progress is saved and shown.
- [Destinations](https://api.trymirio.com/docs/destinations.md): Slack, your own Postgres or Supabase database, email, webhooks; `mirio destinations add`; category and fit filters for email and Slack.
- [Webhooks and email](https://api.trymirio.com/docs/webhooks.md): payload, signature verification, retries, replay.
- [Agent-native forms](https://api.trymirio.com/docs/agents.md): the `agents` policy, `schema.json`, submitting as a declared agent.

## Reference

- [HTTP API](https://api.trymirio.com/docs/api.md): submission endpoint, project API, read API, error codes.
- [Usage](https://api.trymirio.com/docs/limits.md): free during the beta, one plan with every feature; what is counted, the monthly limits and rate limits.

## Rules of thumb for agents

1. Code is the source of truth. Form structure lives in `mirio/forms/<slug>.ts`. The dashboard never edits it.
2. Forms register themselves: `withMirio` (next.config) or `mirio()` (vite/astro config) registers a form when its file is saved in the dev server and runs `mirio sync` during builds. Without a dev server, `npx mirio push`. Then `npx mirio test <slug>` to confirm a round trip.
3. After the human claims the project, run `npx mirio env vercel` (or `netlify`, `print`) so deploy builds register forms. Without the key a build fails only when visitors would be rejected.
4. Never put passwords, card numbers or government ids in a form. Mirio rejects those fields at push.
5. Share the claim link with the human. Going live takes one sign-in.
6. Settings the team changes without a deploy live in Mirio, not the file: `npx mirio destinations add slack --form <slug>` (prints an "Add to Slack" link for the human; or `email` for members, `webhook`, `postgres`), `npx mirio domains add example.com`, `npx mirio review <slug> --ideal "…"`, `npx mirio turnstile set <secret key>` (Cloudflare Turnstile with the site's own widget).
7. Forms accept declared agent submissions by default (`settings.agents: 'accept'`, labeled as agent). Read a form's `schema.json` before submitting as an agent.
8. `<MirioAttribution />` in the root layout is optional: ask the human before adding it. It records which page led to the form and where the visit started.


---

<!-- https://api.trymirio.com/docs/index.md -->

# Mirio quickstart

Mirio puts a form on a site that a coding agent builds, and handles everything after submit. This page is the whole happy path: about two minutes, and no human is needed until the claim at the end. There is no push step to remember: the framework plugin registers forms while you develop and when the site builds.

> **Started in the Mirio dashboard?** If you created the form under **New form** in Mirio, open the form's page and click **Copy prompt**. Give it to your coding agent: it starts with `npx @trymirio/mirio init --link <code>`, which connects this repo to that site (already claimed, no sandbox) and lists the form files to write. Then continue at step 2.

## 1. Set up the project

```bash
npx @trymirio/mirio init --agent <your name>
npm install @trymirio/mirio
```

Agents: name yourselves with `--agent` (for example `claude-code`, `cursor`, `codex`), so the site's owner can see which agent set it up.

**In a monorepo**, run `init` in the app's folder (the one with `next.config`, `vite.config` or `astro.config`); `mirio.json` lives there and every `mirio` command runs from there. Run it at a monorepo root and it stops, names the app folder, and leaves a link code unused.

`init` creates a sandbox project and sets up the repo:

- `mirio.json` (public project id), the secret key in `.mirio/secret` (gitignored), `mirio/client.ts`, `mirio/forms/`.
- **The framework plugin**: wraps `next.config.*` in `withMirio(...)`, or adds `mirio()` to `vite.config.*` / `astro.config.*`. It works alongside other config wrappers (`withSentryConfig`, `withMDX` and the like) in any order. If the config has a shape it can't edit safely, it prints the two lines to add.
- **The CSS**: next to `@import "tailwindcss"` in your global stylesheet it adds `@trymirio/mirio/theme.css` and the `@source` line, plus `@trymirio/mirio/themes/shadcn.css` on shadcn/ui sites that use shadcn's color variables (it checks `components.json` and that your CSS defines them; a site with its own tokens keeps Mirio's defaults). Without Tailwind it tells you to import `@trymirio/mirio/styles.css`.
- A short "Mirio forms" section in `AGENTS.md` or `CLAUDE.md`.

It prints a claim link. Keep it; the human needs it in step 5. Sandbox projects accept submissions from localhost only.

## 2. Write the schema

`mirio/forms/waitlist.ts`:

```ts
import { defineForm } from '@trymirio/mirio/schema';

export const waitlist = defineForm({
  slug: 'waitlist',
  name: 'Waitlist',
  pages: [
    {
      fields: [
        { key: 'email', type: 'email', label: 'Work email', autocomplete: 'email', required: true },
        { key: 'name', type: 'short_text', label: 'Name', autocomplete: 'name' },
        { key: 'role', type: 'dropdown', label: 'Role', options: ['Founder', 'Engineer', 'Designer', 'Other'] },
        { key: 'consent', type: 'consent', label: 'Email me when there is news', required: true },
      ],
    },
  ],
  settings: {
    success: { type: 'message', title: 'You are on the list', message: 'We will email you when your spot opens.' },
  },
});
```

See [Form schema](https://api.trymirio.com/docs/schema.md) for every field type and constraint. Notifications, allowed domains and triage are set in Mirio, not here (`npx mirio destinations add email you@company.com --all-forms`, `mirio domains`, `mirio review`).

## 3. Render it

```tsx
// components/waitlist-form.tsx
'use client';

import { Form } from '@trymirio/mirio';
import { mirio } from '@/mirio/client';
import { waitlist } from '@/mirio/forms/waitlist';

export function WaitlistForm() {
  return <Form schema={waitlist} client={mirio} />;
}
```

Then use `<WaitlistForm />` in any page. In Next.js (App Router) the form has to live in a client component like this one (`'use client'` at the top): `mirio`, the client, can't be passed from a server component. Pass it as `client`, or wrap the app once in [MirioProvider](https://api.trymirio.com/docs/components/provider.md); without either, `<Form>` throws and says so.

`<Form>` with no children renders every field, validation, the submit button and the success state; multi-page schemas render one step at a time. It inherits your site's font and follows its dark mode. Adjust it with `theme`, `size`, `layout` and `classNames` ([Theming](https://api.trymirio.com/docs/theming.md)) or compose it yourself ([Components](https://api.trymirio.com/docs/components.md)).

**Optional, so ask the site owner first:** `<MirioAttribution />` (from `@trymirio/mirio`), added once to the root layout, lets each response say which page on the site led to the form and where the visit started. It keeps a small record of the visit in the visitor's browser tab (`sessionStorage`). It takes no props, so a server layout can render it. See [Attribution and hidden fields](https://api.trymirio.com/docs/attribution.md).

If the site sets a Content Security Policy, add the Mirio API to `connect-src` (`https://api.trymirio.com`, and `http://localhost:4000` against a local API).

## 4. Run the dev server and test

```bash
npm run dev
npx mirio test waitlist
```

While the dev server runs, saving a file in `mirio/forms/` registers that form (one line in the terminal: `[mirio] waitlist: v2 registered (development)`, or the validation issues). `mirio test` sends a sample submission end to end and reads it back. Submit the form on localhost yourself too; `npx mirio submissions waitlist` shows what landed.

No dev server (a script, CI)? `npx mirio push` does the same registration by hand.

## 5. Claim, then give the host the key

Tell the human the form works locally and share the claim link (`npx mirio claim` prints it again). They sign in with Google, GitHub or a code sent to their email, accept the terms and name the production domains. Then, once:

```bash
npx mirio env vercel     # or: npx mirio env netlify, npx mirio env print
```

This puts `MIRIO_SECRET_KEY` into the host's build environment (on stdin, never echoed). From then on every deploy registers its forms during the build, tagged production or preview from the host's environment; production builds set the questions the dashboard shows.

Without the key a build still checks: it **fails** only if visitors would be rejected (the project is unclaimed, or a form was never registered) and **warns** when questions changed since the last registration (those responses are accepted and flagged). `npx mirio sync` runs the same step in any other CI.

## What happens after submit

- The server validates every submission against the registered schema and normalizes values (trimmed, lowercased emails, E.164 phone numbers).
- Spam is scored (honeypot, time to submit, disposable emails, link stuffing, optional Turnstile) and goes to a spam view. Nothing is discarded.
- Submissions are stored by stable field id, so renaming a field with `renamedFrom` keeps its data together.
- Completed submissions go to verified email addresses, Slack (connect a channel with "Add to Slack", or `mirio destinations add slack --form <slug>` for a link a person approves), your database and signed webhooks.
- Multi-step progress is saved at each step as a partial submission. Partials never trigger notifications.

---

<!-- https://api.trymirio.com/docs/when-to-use.md -->

---
title: When to use Mirio
description: What Mirio is for, when another tool fits better, and how it compares to form endpoints, hosted builders and inbound tools.
---

# When to use Mirio

Mirio is inbound for sites that a coding agent builds and maintains, starting with the demo request form: the building blocks and automations an agent needs so every request is read in seconds and the good ones answered in minutes. The form lives in the site's own code, rendered with the `@trymirio/mirio` React components; Mirio's backend handles everything after submit: validation, spam protection, versioned storage, partial responses, triage (summary, category, fit), and delivery to email, Slack, webhooks or your own database.

## Use Mirio when

- An agent (Claude Code, Cursor, Codex, v0 and similar) builds or edits the site, and you want it to add a working form without a person setting up a backend.
- You want every demo request read, sorted by fit and in Slack within seconds, without setting up sales operations first.
- The form should look like the rest of the site: it inherits the site's fonts and shadcn theme, and every piece can be restyled in code.
- You need what happens after submit to be reliable: server-side validation, spam filtering, retries, and data that stays consistent when the questions change.
- You want responses in one place your team can act on (an inbox per form, sorted by triage), and optionally in your own database or Slack.
- A multi-step form should save progress, so you can see where people drop off.

## Use something else when

- **Your app already has a database and an API for this data.** Write the form against your own backend.
- **You want a hosted form link with no site of your own.** A hosted builder such as Tally or Typeform fits better.
- **You need a research survey** with panels, quotas and analysis. Use a survey tool.
- **You run a large sales team with territories and Salesforce routing.** An inbound platform such as Default or Chili Piper fits better; Mirio's webhooks and database destination can still feed it.
- **You need payments, file uploads or e-signatures in the form today.** Mirio doesn't do these yet.
- **The site isn't built with React.** Plain HTML posting and Vue and Svelte components are on the roadmap.

## How it compares

| | Mirio | Form endpoints (Formspree, Basin) | Hosted builders (Tally, Typeform) | Inbound platforms (Default, Chili Piper) |
| --- | --- | --- | --- | --- |
| Where the form lives | In your site's code | In your site's code | On the builder's page or an embed | Their form, or yours connected to their script |
| Who builds it | Your agent, from a typed schema file | You write the HTML | You, in the builder's editor | Your team, in their form builder or your code |
| Components | Styled and headless React components that match your site | None; bring your own markup | The builder's own design | Their form builder's, or bring your own |
| Validation | Server-side against the registered schema | Basic | Built into the builder | In their form builder |
| Questions change over time | Versioned; renamed fields keep their data | Fields are whatever gets posted | Managed in the editor | Managed in their app |
| Multi-step progress saved | Yes | No | On some plans | Abandoned-form follow-up on some plans |
| After submit | Spam filtering, triage, inbox, email, Slack, webhooks, your database | Email, webhooks, integrations | Results view, integrations | Enrichment, qualification, routing to reps, booking, CRM sync |
| Agent setup | One command with no account; a person signs in once to go live | Sign up first, then paste an endpoint | Sign up, build in the editor | A sales-led contract, then workflows set up in their app |

## Start

```bash
npx @trymirio/mirio init --agent <your name>
```

Then follow the [quickstart](https://api.trymirio.com/docs/index.md).

---

<!-- https://api.trymirio.com/docs/claiming.md -->

# Claiming and the sandbox

`mirio init` needs no account, so an agent can go from a prompt to a tested form on localhost without a human. The trade-off is that anonymous projects must not collect real people's data. Unclaimed projects therefore run in a sandbox.

## Sandbox rules

- Submissions are accepted only from localhost origins (`localhost`, `127.0.0.1`, `*.localhost`, any port). A public origin gets HTTP 403 with code `project_unclaimed` and the claim link in the hint.
- Requests made with the project's secret key (the CLI, server code) are accepted without an origin check, because they are the owner's own test traffic.
- Sandbox data expires after 72 hours. Read it with `mirio submissions`.
- No emails or webhooks are sent from a sandbox project.
- `mirio status` and `mirio push` warn; `mirio check` fails a production build.

## Claiming

The claim link looks like `https://trymirio.com/claim/<token>`. A human opens it, signs in with Google, GitHub or a code sent to their email, picks or creates a workspace, accepts the terms, and enters the production domains (one per line; `example.com`, `https://app.example.com`, or `*.example.com`). The project becomes live and starts accepting submissions from those origins. The secret key does not change.

Claiming gives every live form an identified owner who has accepted the terms, which matters under GDPR and for abuse response.

## Content Security Policy

Sites with a CSP must list the API in `connect-src`: `https://api.trymirio.com` in production and your local API URL in development. Without it the browser refuses the request before it reaches Mirio.

## Connecting a site created in the dashboard

A site can also start in the dashboard (sign up at [trymirio.com/signup](https://trymirio.com/signup)): **New form** creates the site (already yours, no claim step) and a draft form. The draft's page has **Copy prompt**: it holds a one-time setup command for the coding agent,

```bash
npx @trymirio/mirio init --link mil_XXXXX-XXXXX-XXXXX-XXXXX
```

which writes `mirio.json` and `.mirio/secret` for that site and lists the drafts waiting for their files. The agent then writes `mirio/forms/<slug>.ts`; the first registration turns the draft into a live form and keeps the notifications and triage settings you already set up. Codes work once and expire after 24 hours; copy the prompt again for a new one. To move a site to another repo, open the site under **Sites** and use **Reconnect with a new key** (the old repo's key stops working).

## After claiming

- Add more domains any time: `npx mirio domains add acme.com` (or the site's page under Sites in the dashboard); `acme.com` also covers `www.acme.com`, and the other way round. Domains belong to the site, not to a form. Localhost keeps working on a live site; those responses are stored as `test`.
- The person who claims the site (or creates it in the dashboard) gets email notifications on every form, including forms added later, unless a form already has a destination. Add teammates to the workspace to notify them too (email goes to members only), or use Slack for shared channels.
- `mirio status` shows `live` and `mirio check` passes.

---

<!-- https://api.trymirio.com/docs/cli.md -->

# CLI

The CLI ships inside the `@trymirio/mirio` package. Run it with `npx @trymirio/mirio <command>` before the package is installed, or `npx mirio <command>` after. Every command accepts `--json` for machine-readable output on stdout. Errors say what went wrong and what to do next. Exit codes: 0 ok, 1 error, 2 `check` failed.

Configuration: `mirio.json` at the repo root (`projectId`, `apiUrl`, `formsDir`), secret key in `.mirio/secret` (gitignored). `MIRIO_SECRET_KEY` and `MIRIO_API_URL` override both, which is what CI uses.

## `mirio init`

Creates a sandbox project and sets up the repo.

```bash
npx @trymirio/mirio init [--agent claude-code] [--name "Marketing site"] [--api-url https://api.trymirio.com] [--forms-dir mirio/forms] [--force]
```

Writes `mirio.json`, `.mirio/secret`, `mirio/client.ts`, `mirio/forms/`, adds `.mirio/` to `.gitignore`, and appends a short "Mirio forms" section to `AGENTS.md` and `CLAUDE.md` (whichever exist; creates `AGENTS.md` if neither). Prints the claim link. Refuses to overwrite an existing `mirio.json` without `--force`. Provisioning is rate limited per IP. In a monorepo, run it in the app's folder: at a monorepo root (no `package.json`, a workspace setup, or no React) with an app below it, it stops before doing anything (a link code stays unused) and names the app folders, Next.js and Astro apps first; `--force` sets up the current folder anyway. The install hint matches your package manager.

`--agent <name>` tells Mirio which coding agent ran the command (agents should name themselves). Without it the CLI uses `MIRIO_AGENT`, then `AI_AGENT`, then `CLAUDECODE=1` (Claude Code); `init --link` sends it too.

### `mirio init --link <code>`

Connects the repo to a site that was started in the Mirio dashboard (New form). The dashboard puts the command, with a one-time code, at the top of the prompt it gives you for the form; codes work once and expire after 24 hours.

```bash
npx @trymirio/mirio init --link mil_XXXXX-XXXXX-XXXXX-XXXXX [--force]
```

It does everything `init` does (config, `.mirio/secret`, `mirio/client.ts`, the plugin, CSS and the AGENTS.md section) but uses the site created in the dashboard, which is already claimed, so there is no claim link. It prints `Connected to <site>` and the forms waiting for a file:

```
✓ Connected to Acme marketing (prj_…)
Forms waiting for a file:
  mirio/forms/waitlist.ts — Waitlist
      Template: waitlist
  mirio/forms/quote.ts — Quote request
      A short intake for people who want a custom quote: what they need built, rough budget…
```

Write each file with `defineForm` and the same slug; the dev server (or `mirio push`) registers it and the draft becomes the form. `--json` returns the project id and the drafts (never the key). An expired or used code asks you to copy a fresh prompt from the form's page; a site that is already connected to another repo returns the API's hint (copy `MIRIO_SECRET_KEY` from that repo, or create a reconnect code on the site's page under Sites). `--force` replaces an existing `mirio.json`.

### Setup edits

Both forms of `init` also set up the site, unless you pass `--no-setup`:

- **Framework plugin.** Next.js: wraps the default export of `next.config.(ts|mjs|js)` in `withMirio(...)` and adds the import (handles `export default nextConfig`, `export default { … }` and `module.exports = …`). Vite and React Router: adds `mirio()` to `plugins` in `vite.config.*`. Astro: adds `mirio()` to `vite.plugins` in `astro.config.*`. When the file has a shape it doesn't recognize, nothing is written and the two lines to add are printed.
- **CSS.** With Tailwind v4, adds `@import "@trymirio/mirio/theme.css"` and the `@source` line after `@import "tailwindcss"` in the global stylesheet; on shadcn/ui sites (`components.json`, whose `tailwind.css` path is used) also `@import "@trymirio/mirio/themes/shadcn.css"`. With Tailwind v3 it adds `@trymirio/mirio/styles.css` (and `themes/shadcn-v3.css`) at the top. Without Tailwind it prints `import '@trymirio/mirio/styles.css'`.

## `mirio push [slug] [--env production|preview|development]`

Loads every schema in the forms directory, validates it locally, and registers it. Prints the version number and the diff from the previous version. Warns while the project is unclaimed. With the framework plugin you rarely need it: the dev server registers a form when its file is saved, and builds run `sync`. The push is tagged with its source (see `sync`); from a laptop that is `development`, so it never changes the questions the dashboard shows for a live form. Pass `--env` to override.

```
✓ waitlist  v3 (new version)
    + role (dropdown)
    ~ name → full_name
⚠ Project is unclaimed. Public origins are rejected until it is claimed: https://trymirio.com/claim/…
```

## `mirio test [slug]`

Sends a sample submission built from the schema, with the secret key and a test flag, then reads it back. Test submissions are stored with status `test` and never count as responses or toward the response limit (triage still reviews them, at most 20 per form a day, and those reviews count toward the triage quota), and never trigger notifications.

## `mirio status`

Project mode (sandbox or live), claim link, allowed origins, delivery destinations, drafts created in Mirio that are still "Waiting for a file: mirio/forms/<slug>.ts (<name>)", and a table of forms with version, 7-day submissions, last submission, the agents policy, whether triage is on and whether an ideal response is set (read from Mirio). Warns when review is on without an ideal response (fit levels need one: `mirio review <slug> --ideal "…"`), prints one line per schema that still carries moved settings (`notifyEmails`, `allowedOrigins`, `review`), and flags forms whose local schema differs from what was registered.

**Updates:** `status` and `sync` say when a newer `@trymirio/mirio` is on npm ("@trymirio/mirio 0.1.5 is out (you have 0.1.4). What changed: https://trymirio.com/docs/changelog · Upgrade: pnpm add @trymirio/mirio@latest"; `--json` has it as `update`). They ask the registry at most once a day (cached in `~/.cache/@trymirio/mirio`), give up after 1.5 seconds and never fail a command; the dev server's sync and CI builds don't check. `MIRIO_NO_UPDATE_CHECK=1` turns it off. See the [changelog](https://api.trymirio.com/docs/changelog.md).

## `mirio sync [--env production|preview|development]`

The build step the framework plugin runs (`withMirio` during `next build`, `mirio()` during `vite build`); call it yourself in any other CI.

- **With a key** (`MIRIO_SECRET_KEY`, or `.mirio/secret` locally): registers every form, tagged with its source.
- **Without one**: checks the registered forms through the public schema endpoint. It **fails** (exit 2) only when visitors would be rejected: the project is unclaimed, or a form is not registered yet (a new form, or a draft created in Mirio whose file has not been registered). It **warns** when a form's questions changed since the registered version (those responses are accepted and flagged).

An unclaimed project fails builds on a deploy host or in CI and only warns on a local build. If Mirio can't be reached, the build continues with a warning.

The source comes from the host: Vercel (`VERCEL_ENV`, `VERCEL_GIT_COMMIT_REF`, `VERCEL_GIT_COMMIT_SHA`, `VERCEL_URL`), Netlify (`CONTEXT`, `BRANCH`, `COMMIT_REF`, `DEPLOY_URL`), Cloudflare Pages (`CF_PAGES_BRANCH`, `CF_PAGES_COMMIT_SHA`, `CF_PAGES_URL`; production on `MIRIO_PRODUCTION_BRANCH` or `main`), GitHub Actions (`GITHUB_REF_NAME`, `GITHUB_SHA`; same branch rule), Render (`RENDER`, `IS_PULL_REQUEST`, `RENDER_GIT_BRANCH`, `RENDER_GIT_COMMIT`), Railway (`RAILWAY_ENVIRONMENT_NAME`, `RAILWAY_GIT_BRANCH`, `RAILWAY_GIT_COMMIT_SHA`); GitLab, CircleCI, Buildkite, Jenkins, Bitbucket Pipelines, Azure Pipelines and Travis by their branch and pull/merge request variables (production on `MIRIO_PRODUCTION_BRANCH`, else the provider's default branch when it says, else `main`; preview otherwise); and any other build server that sets `CI` (production). `MIRIO_ENV` overrides. A build with no host signal and no `CI` is development, a local `next build` included, so building a branch on your laptop never changes production; if your build server doesn't set `CI`, set `MIRIO_ENV=production` (the build output says so). Production registrations set the questions the dashboard shows; preview and development ones never do.

```
mirio sync production (vercel, main@1a2b3c4) · 3 forms · registering
✓ demo-request v4 registered
✓ waitlist v2 unchanged
```

## `mirio env vercel|netlify|print`

Puts the project's secret key into the host so deploy builds can register forms.

- `vercel`: `vercel env add MIRIO_SECRET_KEY production` and `… preview`, with the key on stdin. Needs the Vercel CLI, logged in and `vercel link`ed.
- `netlify`: `netlify env:set MIRIO_SECRET_KEY … --context production` and `deploy-preview`. Needs the Netlify CLI, logged in and `netlify link`ed.
- `print`: prints `MIRIO_SECRET_KEY=sk_…` to your terminal so you can paste it into any host's settings.

Mirio never prints the key for `vercel` and `netlify`, and redacts it from the host CLI's output. When the host CLI is missing, not logged in, not linked, or the variable already exists, the error says what to run.

## `mirio check [--allow-sandbox]`

A strict local check. Exits 2 when the project is unclaimed or any local schema differs from the registered one (or was never registered). Builds don't need it any more: the framework plugin runs `sync`, which fails only when visitors would be rejected.

## `mirio claim [--open] [--wait]`

Prints the claim link. `--open` opens it in a browser. `--wait` polls until the project is live.

## `mirio submissions [slug] [--status all|complete|partial|spam|test] [--limit 20]`

Reads submissions through the project API, with each response's kind (complete, partial, spam, test), when it came in and its first answers. For sandbox projects this is the agent's own test data and expires after 72 hours.

## `mirio destinations …`

Wire delivery without the dashboard. Destinations belong to a form: pass `--form <slug>`, or `--all-forms` to create one per form.

```bash
npx mirio destinations list
npx mirio destinations add slack --form demo-request      # "Add to Slack": prints a link for a person, waits for the channel
npx mirio destinations add slack https://hooks.slack.com/services/… --all-forms
npx mirio destinations add postgres "postgres://…pooler.supabase.com:6543/postgres" [--table demo_requests] --form demo-request
npx mirio destinations add email founders@example.com --form demo-request      # workspace members only
npx mirio destinations add email sales@example.com --form demo-request --categories "Sales lead,Partnership" --fit high,medium
npx mirio destinations add slack https://hooks.slack.com/services/… --form demo-request --fit high
npx mirio destinations add slack https://hooks.slack.com/services/… --form demo-request --group "Urgency: This week"
npx mirio destinations add webhook https://example.com/hooks/mirio --form demo-request      # prints the signing secret once
npx mirio destinations remove dst_…
npx mirio destinations test dst_…
```

**Slack without a URL** prints a 30-minute link to "Add to Slack" for a person in the site's workspace (an agent can't click through Slack's install screen) and waits up to 10 minutes for the channel to appear; `--no-wait` prints the link and exits, and `--json` returns `{ connectUrl, expiresAt, destinations }` without waiting. Claimed sites only.

Webhook URLs must be public `https://` addresses, and databases public hosts: Mirio refuses localhost, private ranges and internal names (see [Destinations](https://api.trymirio.com/docs/destinations.md)).

Email goes only to workspace members (no verification step); for shared inboxes and aliases use Slack. Adding a non-member address fails with the API's hint. Connection strings are encrypted at rest and never printed back. See [Destinations](https://api.trymirio.com/docs/destinations.md).

`--categories` (comma-separated, matching the form's review categories) and `--fit` (`high`, `medium`, `low`) filter what an **email or Slack** destination sends, using the [AI review](https://api.trymirio.com/docs/ai-review.md). Responses without a review (review off, or the review failed) are always sent. The flags are rejected for webhooks and Postgres, which receive every response with the review attached. `destinations list` shows each filter in plain words ("Sales lead or Partnership, high or medium fit"); `--json` includes the `filter` object.

## `mirio domains list|add <domain>|remove <domain>`

The site's production domains (allowed origins). Visitors from them can submit once the project is claimed; localhost always works. Accepts `example.com`, `www.example.com`, `*.example.com` or a full origin with a port. A domain and its `www.` form count as one site: adding either allows both (most sites redirect one to the other). API: `GET/POST/DELETE /v1/project/domains`.

```bash
npx mirio domains add example.com
npx mirio domains list
npx mirio domains remove staging.example.com
```

## `mirio review <slug> [--ideal "…"] [--summary "…"] [--categories "A,B"] [--group "Name: A, B"] [--remove-group "Name"] [--off|--on]`

Triage for one form. With no flags it shows the settings; flags change them and keep the rest (so `--ideal` alone keeps the categories). The ideal response describes a great respondent in plain words and enables fit levels; `--summary` says what each summary should focus on (3 to 500 characters); categories are 2 to 12 labels; `--group "Urgency: This week, Later"` adds a group triage sorts into, or replaces the one with that name (repeatable, up to 5), and `--remove-group` drops one. API: `GET/PUT /v1/project/forms/:slug/review`. See [AI review](https://api.trymirio.com/docs/ai-review.md).

```bash
npx mirio review demo-request --ideal "Product or research leads at 20–500 person software companies who want to start this quarter."
```


## `mirio turnstile [set <secret key> [--site-key <key>]|remove]`

[Cloudflare Turnstile](https://api.trymirio.com/docs/spam.md#turnstile) with your own widget. `set` gives Mirio the widget's secret key so it can check visitors' tokens: the site key comes from `settings.turnstileSiteKey` in your schema files (`--site-key` when they use more than one), Mirio checks the secret key with Cloudflare, and it is stored encrypted and never printed back. With no action it lists the forms that set a site key and whether their tokens are checked; `remove` deletes the secret key. API: `GET/PUT/DELETE /v1/project/turnstile`.

```bash
npx mirio turnstile set 0x4AAAAAAA…
npx mirio turnstile
```

---

<!-- https://api.trymirio.com/docs/schema.md -->

# Form schema

Each form is a TypeScript file in `mirio/forms/<slug>.ts` that exports the result of `defineForm`. `defineForm` validates the schema at module load, so a bad schema fails fast in the site's own build and in `mirio push`.

```ts
import { defineForm } from '@trymirio/mirio/schema';

export const contact = defineForm({
  slug: 'contact',            // lowercase letters, numbers, dashes; stable; used in the URL
  name: 'Contact',
  description: 'Shown in the dashboard only',
  pages: [ /* one or more pages */ ],
  settings: { /* optional */ },
});
```

## Pages

A form is a list of pages. A classic form has one page; a multi-step form has many. Pages are the unit for partial saves and step completion.

```ts
pages: [
  { key: 'about', title: 'About you', description: 'Takes a minute', fields: [ /* … */ ] },
  { key: 'project', title: 'Your project', fields: [ /* … */ ] },
]
```

`key`, `title` and `description` are optional. Every page needs at least one field.

## Fields

Every field has a stable `key` (unique across all pages), a `type`, and a `label`. Optional on every field: `help`, `placeholder`, `required`, `renamedFrom`, `defaultValue`.

| Type | Value stored | Constraints |
| --- | --- | --- |
| `short_text` | string, trimmed | `minLength`, `maxLength` (default 500), `pattern` (regex source) |
| `long_text` | string, trimmed | `minLength`, `maxLength` (default 10000), `pattern` |
| `email` | string, lowercased | |
| `phone` | E.164 string, e.g. `+15555550123` | `defaultCountry` (ISO-2, default `US`) for numbers typed without a country code |
| `url` | normalized URL; `https://` added when no scheme | |
| `number` | number | `min`, `max`, `integer` |
| `single_choice` | one option value | `options` (required) |
| `multiple_choice` | array of option values | `options` (required), `minSelected`, `maxSelected` |
| `dropdown` | one option value | `options` (required) |
| `yes_no` | boolean | `options` (optional, exactly two: the labels shown for yes and no) |
| `rating` | integer `min`..`max` | `min` (default 1, may be 0), `max` (default 5, 2 to 10) |
| `date` | `YYYY-MM-DD` | `min`, `max` as ISO dates |
| `consent` | boolean; `required` means it must be true | |
| `hidden` | string; not rendered | `defaultValue` |

Also on every field: `autocomplete` (the HTML autocomplete token: `name`, `given-name`, `email`, `tel`, `organization`, `url`), `prefill: { query: 'utm_term' }` to take the initial value from a URL parameter (hidden fields default to their own key; when the form's page lacks it, the visit's landing page is used, see [hidden fields](https://api.trymirio.com/docs/attribution.md#hidden-fields)), and `showWhen` for [conditional logic](https://api.trymirio.com/docs/conditional-logic.md).

There is no separate name field. Use `short_text` with `autocomplete: 'name'` (or `given-name` and `family-name` for two fields); browsers then autofill it, and `schedule` success links pick it up.

`options` accept strings or `{ value, label }` objects:

```ts
{ key: 'plan', type: 'dropdown', label: 'Plan', options: ['Free', { value: 'pro', label: 'Pro ($29/mo)' }] }
```

### Renaming a field

Keys are what the site code and the API use, but submissions are stored by a stable field id. Declare the old key so the data stays together:

```ts
{ key: 'full_name', type: 'short_text', label: 'Full name', renamedFrom: ['name'] }
```

The submissions table shows one column, and the version diff reports a rename rather than a removal plus an addition.

### Fields Mirio refuses

Keys or labels that look like passwords, card numbers, CVV codes or social security numbers are rejected by `defineForm` and by `push`. Mirio is not a place for secrets. Use a payment provider for cards.

## Settings

The schema file holds what the visitor sees and what the form accepts:

```ts
settings: {
  success: { type: 'message', title: 'Thanks', message: 'We will be in touch.' },
  // or: success: { type: 'redirect', url: 'https://example.com/thanks', prefill: { ref: 'email' } },
  // or: success: { type: 'schedule', url: 'https://calendly.com/versive/demo' },   // Calendly or Cal.com, name and email prefilled
  submitLabel: 'Request a demo',
  agents: 'accept',                     // 'accept' (default; declared agents are labeled) | 'block'
  agentNotes: 'What this form is for and what good answers look like',
  turnstileSiteKey: '0x4AAAAAAA…',      // optional: your Cloudflare Turnstile widget; Mirio also needs its secret key (see Spam)
}
```

`schedule` sends the visitor to a Calendly or Cal.com page with `name`, `email` and any `utm_*` parameters filled in, so the demo is booked in the same flow. The visitor's browser runs this code, so `success` from the file is what they see. Settings are applied at registration and are not part of the schema version. Changing a label, option or constraint is; every distinct schema becomes a new version with a visible diff. `agents` also accepts the old `'allow'` and `'flag'`, both meaning `'accept'`.

### What lives in Mirio instead

Everything the team changes without a deploy lives in Mirio (the dashboard, the CLI or the API), not in the file:

| Setting | Where |
| --- | --- |
| Allowed domains (per site) | `npx mirio domains add example.com`, dashboard: Sites → the site → Domains |
| Notifications and integrations (per form) | `npx mirio destinations add email\|slack\|webhook\|postgres … --form <slug>` or `--all-forms`; email goes to workspace members only. See [Destinations](https://api.trymirio.com/docs/destinations.md). |
| Triage: ideal response, summary, categories, on/off | `npx mirio review <slug> --ideal "…"`. See [AI review](https://api.trymirio.com/docs/ai-review.md). |
| Turnstile secret key (per site) | `npx mirio turnstile set <secret key>`. See [Turnstile](https://api.trymirio.com/docs/spam.md#turnstile). |

`settings.notifyEmails`, `settings.allowedOrigins` and `settings.review` still validate for one release. The first push imports `notifyEmails` (member addresses only) and `review` when Mirio has nothing set for that form; per-form `allowedOrigins` are dropped (domains belong to the site). `mirio status` and the dev server print one line per schema that still has them; remove them from the file.

## Versions

`mirio push` computes a hash of the canonical schema (pages, fields and their properties, not settings). A new hash becomes a new version. Submissions record the version they were made against. If a form is submitted with a hash that was never pushed, the submission is accepted, validated against the latest pushed version, flagged `unregistered_schema`, and the owner gets one email. Run `mirio push` to clear the flag for future submissions.

---

<!-- https://api.trymirio.com/docs/conditional-logic.md -->

# Conditional logic

Show a field or a whole page only when earlier answers match. Conditions live in the schema and are evaluated by the components and by the server, so a hidden field is never required and never stored.

```ts
{ key: 'role', type: 'dropdown', label: 'Role', options: ['Founder', 'Researcher', 'Other'], required: true },
{ key: 'role_other', type: 'short_text', label: 'Which role?', required: true,
  showWhen: { field: 'role', op: 'eq', value: 'Other' } },
```

Page-level:

```ts
{ title: 'Your team', showWhen: { field: 'role', op: 'in', value: ['Founder', 'Researcher'] }, fields: [ … ] }
```

Groups:

```ts
showWhen: { all: [ { field: 'team_size', op: 'gte', value: 10 }, { any: [ { field: 'interest', op: 'contains', value: 'surveys' }, { field: 'timeline', op: 'neq', value: 'Just looking' } ] } ] }
```

Operators: `eq`, `neq`, `in`, `notIn`, `contains`, `notContains` (strings and multiple choice), `gt`, `gte`, `lt`, `lte` (numbers, dates), `empty`, `notEmpty`.

Rules:

- A condition may reference fields on the same page or earlier pages, never later ones. `defineForm` checks this.
- A page with no visible fields is skipped; the progress indicator counts visible pages only.
- Hidden values are dropped before a partial save or a submit, and the server drops them again.
- Conditions are part of the schema version, so changing one creates a new version.

Explicit jumps and calculated fields are not supported. If `showWhen` turns out not to be enough, [tell us](https://trymirio.com/contact).

---

<!-- https://api.trymirio.com/docs/attribution.md -->

# Attribution and hidden fields

Every response records where the person came from, so a form linked from twenty pages tells you which page sent them, and a campaign isn't lost when the visitor browses before filling it in:

| | Stored as | Example |
| --- | --- | --- |
| The page with the form (origin and path, no query string) | `meta.pageUrl` | `https://acme.com/demo` |
| The page on your site that led to the form, or the other site that linked straight to it | `meta.referrer` | `/pricing`, or `https://news.ycombinator.com` |
| The first page of the visit, when it isn't the form's page | `meta.landingPage` | `/blog/launch` |
| The other site the visit arrived from, when the form's page wasn't the first | `meta.entryReferrer` | `https://www.google.com` |
| Campaign tags from the form's page, else from the landing page | `meta.utm` | `{ "source": "google", "medium": "cpc" }` |

It shows on each response (Came from, Landing page, Visit came from), in Slack and email notifications ("From /pricing · via google / cpc · landed on /blog/launch"), in Insights (Where people come from, Pages that led here), in the CSV and API exports (`page_url`, `referrer`, `landing_page`, `entry_referrer`, `utm_*`), and in webhooks and database rows (`meta`).

## Record it on every page (optional)

A page with a form records it by itself. To also know the pages a visitor saw *before* reaching the form (which page sent them, where the visit started), add `MirioAttribution` once to the root layout. It's optional: a choice for the site owner, since it runs on every page. It takes no props and renders nothing, so a Next.js server layout can render it:

```tsx
// app/layout.tsx
import { MirioAttribution } from '@trymirio/mirio';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <MirioAttribution />
        {children}
      </body>
    </html>
  );
}
```

Outside React, call `startAttribution()` from `@trymirio/mirio/client` once per page load. Without either, responses still carry the form's own page, the site that linked straight to it and its campaign tags.

## Privacy

- Other sites are recorded as their origin only (`https://www.google.com`), never their path or query, which can hold search terms or tokens. Pages on your site are recorded as paths, without query strings. Mirio's API trims whatever a client sends to this, including older versions that send the full `document.referrer`.
- The visit record lives in the visitor's own `sessionStorage` for that tab, until the tab closes. It's sent only with a submission. No cookies, nothing shared across sites.
- Turn it off with `createClient({ projectId, attribution: false })` in `mirio/client.ts`: responses then carry only what the form's page knows.
- **Consent.** In the EU and UK, keeping data in a visitor's browser and sending it later can need consent under the ePrivacy rules, even without cookies, when it isn't strictly necessary for the form. The site owner decides. If your site asks for consent for analytics, treat attribution the same way: pass `attribution: false` until the visitor agrees, or leave it off. Mention Mirio in your privacy notice either way ([what Mirio stores](https://trymirio.com/legal/privacy#3-responses-we-store-for-customers)).

## Hidden fields

A `hidden` field isn't shown; its value comes from the URL, like Typeform's hidden fields. Link to `/demo?plan=pro&partner=acme` and:

```ts
fields: [
  { key: 'plan', type: 'hidden', label: 'Plan' },                                    // ?plan=…
  { key: 'partner', type: 'hidden', label: 'Partner', prefill: { query: 'partner' } }, // any parameter name
  { key: 'source', type: 'hidden', label: 'Source', defaultValue: 'website' },         // a fixed value
]
```

A hidden field reads the parameter named after its key, or `prefill.query`. When the form's page doesn't have the parameter, it reads it from the landing page of the visit, so `acme.com/?plan=pro` → `/pricing` → `/demo` still fills `plan` (with `MirioAttribution` in the layout). `prefill.query` works on visible fields too, and `initialValues` on `<Form>` sets values from code (it wins over the URL). Hidden values are stored and delivered like any answer.

---

<!-- https://api.trymirio.com/docs/components.md -->

# Components

`@trymirio/mirio` has two layers. **Headless primitives** (`@trymirio/mirio/headless`) carry behavior and accessibility with no styling: form state, validation, conditional logic, page navigation, partial saves, focus management, labels and aria. **Styled components** (`@trymirio/mirio`) sit on top and look finished out of the box, authored in Tailwind and themed with `--mirio-*` CSS variables. Both are replaceable: restyle with the `theme`, `size`, `layout` and `classNames` props, variables or classes, or start from the primitives.

## Zero-markup form

```tsx
import { Form } from '@trymirio/mirio';
import { mirio } from '@/mirio/client';
import { waitlist } from '@/mirio/forms/waitlist';

<Form schema={waitlist} client={mirio} />
```

With no children, `Form` renders every page from the schema: one page gives you the fields and a submit button; several pages give you `MultiStep` with a progress line, Back and Next. After submit it shows the `settings.success` message, or redirects. Wrap the app once in [MirioProvider](https://api.trymirio.com/docs/components/provider.md) to drop the `client` prop.

## Composing

Children replace the automatic layout. `Field` renders any field by key (label, help, the right control, error); the controls, `Label`, `Help`, `FieldError`, `Submit`, `Page`, `Progress` and `MultiStep` can be arranged freely, mixed with your own JSX.

```tsx
import { Form, Field, Submit } from '@trymirio/mirio';

<Form schema={contact} client={mirio} className="grid gap-6">
  <div className="grid grid-cols-2 gap-4">
    <Field name="first_name" />
    <Field name="last_name" />
  </div>
  <Field name="email" />
  <Field name="message" />
  <Submit className="w-auto justify-self-end" />
</Form>
```

Every styled component accepts `className` (merged with tailwind-merge, so your utilities win) and renders `data-mirio="<name>"` for CSS. Hidden fields and pages (`showWhen`) render nothing. See [Styling](https://api.trymirio.com/docs/styling.md) for the three depths of customization.

## All components

| Component | One line |
| --- | --- |
| [Form](https://api.trymirio.com/docs/components/form.md) | The whole form from a schema; auto-renders or takes children. |
| [Field](https://api.trymirio.com/docs/components/field.md) | Label + help + the control for the field type + error, from one `name`. |
| [Input](https://api.trymirio.com/docs/components/input.md) | Single-line control for `short_text`, `email`, `phone`, `url`, `number`. |
| [Textarea](https://api.trymirio.com/docs/components/textarea.md) | Multi-line control for `long_text`. |
| [Select](https://api.trymirio.com/docs/components/select.md) | Styled native select for `dropdown`. |
| [Choice](https://api.trymirio.com/docs/components/choice.md) | Radio group (`single_choice`) or checkbox group (`multiple_choice`). |
| [YesNo](https://api.trymirio.com/docs/components/yes-no.md) | Two segmented buttons with radio semantics for `yes_no`. |
| [Rating](https://api.trymirio.com/docs/components/rating.md) | 1..max buttons with radio semantics and arrow keys for `rating`. |
| [DatePicker](https://api.trymirio.com/docs/components/date-picker.md) | Styled native date input for `date`. |
| [Consent](https://api.trymirio.com/docs/components/consent.md) | Checkbox with inline label for `consent`. |
| [Submit](https://api.trymirio.com/docs/components/submit.md) | Submit button with the label from `settings.submitLabel` and a loading state. |
| [Success](https://api.trymirio.com/docs/components/success.md) | The thank-you card from `settings.success`. |
| [MultiStep](https://api.trymirio.com/docs/components/multi-step.md) | One page at a time with Progress, Back/Next and Submit; also covers `Page` and `Progress`. |
| [Label, Help, FieldError](https://api.trymirio.com/docs/components/label-help-error.md) | The text pieces around a control, and the `requiredIndicator` option. |
| [MirioProvider](https://api.trymirio.com/docs/components/provider.md) | Provide the client and display options once. |
| [Headless](https://api.trymirio.com/docs/components/headless.md) | `useMirioForm`, `FormProvider`, `useForm`, `useField`, `usePage`, `useFormStatus`, `Honeypot`, `Turnstile`, with a reference table of everything the hook returns. |

## Behavior you get for free

- Client validation from the schema, with the same validator the server runs; format errors on blur, "required" on submit; focus moves to the first invalid control.
- Submit with an idempotency key and retries on network errors and 5xx; one logical submit never lands twice.
- Page URL, referrer and UTM parameters captured; a honeypot and time-to-submit as spam signals; Turnstile when a site key is set (Mirio checks it once it has the widget's secret key); agents that declare themselves (`actor`) are labeled.
- Partial saves when a visitor moves to the next step, never on keystrokes.
- Prefill from `initialValues`, `prefill: { query }` and `defaultValue`; `autocomplete` attributes from the schema.
- Conditional fields and pages ([Conditional logic](https://api.trymirio.com/docs/conditional-logic.md)), and `schedule` successes that land on a booking page with name and email filled in.

---

<!-- https://api.trymirio.com/docs/styling.md -->

# Styling

The styled components are authored in Tailwind v4 and read `--mirio-*` CSS variables and two `data-mirio-*` attributes, so the Tailwind source and the compiled CSS look and behave the same. There are five layers, from "do nothing" to "own every class". Most sites stop at the first or second. The interactive [Theming](https://api.trymirio.com/docs/theming.md) page shows each knob live.

## Import the CSS (once)

`mirio init` does this for you. By hand:

**Tailwind v4.** Your Tailwind build generates the utilities the components use, so your own classes override theirs normally:

```css
/* app/globals.css */
@import "tailwindcss";
@import "@trymirio/mirio/theme.css";
@import "@trymirio/mirio/themes/shadcn.css";   /* only on shadcn/ui sites */
@source "../node_modules/@trymirio/mirio/dist";
```

**Anything else** (Tailwind v3, plain CSS, CSS modules). Import the compiled stylesheet. It is scoped under `[data-mirio-root]` (the `Form` root), so it does not touch the rest of the page and has no global reset. On a shadcn/ui site with Tailwind v3, add `@trymirio/mirio/themes/shadcn-v3.css` after it.

```ts
import '@trymirio/mirio/styles.css';
```

## 1. Inherit the site

The form uses your page's font (`--mirio-font: inherit`). On shadcn/ui sites, `themes/shadcn.css` maps every `--mirio-*` token to shadcn's variables (`--primary`, `--primary-foreground`, `--background`, `--foreground`, `--muted`, `--muted-foreground`, `--input`, `--ring`, `--destructive`, `--radius`), so the form matches your buttons and inputs and changes with your theme. `themes/shadcn-v3.css` does the same for the HSL-triplet style (`hsl(var(--primary))`).

## 2. Dark mode follows the site

The built-in dark values apply when the form sits under a `.dark` or `[data-theme="dark"]` ancestor, which is what next-themes and most Tailwind setups toggle. To force it on one form, pass `theme={{ colorScheme: 'dark' }}` (`'light'` forces light, `'auto'` follows the visitor's OS). A form is never dark because of the OS alone unless you ask for `'auto'`. Override the dark values with your own rule:

```css
.dark { --mirio-primary: #a5b4fc; --mirio-primary-fg: #1e1b4b; }
```

## 3. Tokens and the `theme` prop

Every color, the radius, font, sizes and spacing are CSS variables. Set them on `:root`, on `.dark`, or on any wrapper:

```css
:root {
  --mirio-primary: #111827;     --mirio-primary-fg: #ffffff;
  --mirio-bg: #ffffff;          --mirio-fg: #111827;
  --mirio-muted: #f3f4f6;       --mirio-muted-fg: #6b7280;
  --mirio-border: #e5e7eb;      --mirio-ring: #2563eb;
  --mirio-error: #dc2626;       --mirio-input-bg: #ffffff;
  --mirio-radius: 0.5rem;       --mirio-font: inherit;
  --mirio-control-h: 2.5rem;    --mirio-text: 15px;
  --mirio-border-width: 1px;    --mirio-label-weight: 500;
  --mirio-space: 1.25rem;       /* between fields */
  --mirio-gap: 0.5rem;          /* inside a field */
}
```

Or pass `theme` to one form (or to `MirioProvider` for all of them; the form's keys win). It becomes inline variables on the form root:

```tsx
<Form schema={waitlist} theme={{ primary: '#2563eb', radius: 'full', font: 'var(--font-sans)' }} />
```

## 4. `size` and `layout`

`size="sm" | "md" | "lg"` swaps one bundle of tokens (control height, text size, spacing) through `data-mirio-size`. `layout={{ columns: 2 }}` lays the auto-rendered fields (and `Page`) out in a grid; long text, choices, consent and keys listed in `layout.full` span every column, and everything is one column below 640px.

```tsx
<Form schema={demo} size="lg" layout={{ columns: 2, full: ['company_url'] }} />
```

## 5. `classNames` slots, `className`, and owning the source

`classNames` adds classes to every instance of a part: `root`, `form`, `page`, `pageHeader`, `field`, `label`, `help`, `input` (Input, Textarea, Select, DatePicker), `option` (choice rows), `segment` (YesNo), `rating`, `consent`, `error`, `submit`, `button` (Back, Next), `progress`, `success`. On `MirioProvider` they apply to every form (both are kept, the form's after the provider's). They are merged with tailwind-merge before each component's own `className`, so a conflicting utility on the component wins:

```tsx
<Form schema={waitlist} classNames={{ label: 'uppercase tracking-wide', input: 'bg-zinc-50', submit: 'rounded-full' }} />
<Submit className="w-auto" />   {/* composed: beats classNames.submit and the default */}
```

Plain CSS can target the `data-mirio` hooks (`[data-mirio="input"]`, `[data-mirio="submit"]`, …) and `[data-mirio-size]`, `[data-mirio-color-scheme]`.

To change the markup itself, start from `@trymirio/mirio/headless` with your own elements ([Headless](https://api.trymirio.com/docs/components/headless.md)); the styled components are built on the same hooks.

---

<!-- https://api.trymirio.com/docs/theming.md -->

---
title: Theming
description: Try theme, size, layout, colorScheme and classNames live, and copy the props.
preview: theme-playground
---
# Theming

Every knob on this page writes props on `<Form>` (or `MirioProvider`); nothing here needs a stylesheet beyond the one import from [Styling](https://api.trymirio.com/docs/styling.md). Change the controls and copy the code.

## Preview
<!-- preview: theme-playground -->

## Usage
```tsx
import { Form } from '@trymirio/mirio';

<Form
  schema={demoRequest}
  client={mirio}
  theme={{ primary: '#2563eb', radius: 'lg', colorScheme: 'auto' }}
  size="md"
  layout={{ columns: 2 }}
  classNames={{ label: 'uppercase tracking-wide', submit: 'rounded-full' }}
/>
```

Set the same `theme`, `size` and `classNames` once for the whole site on `MirioProvider`; a form's own props win (theme per key, classNames per slot with both kept).

## Props

### `theme`
| Key | Variable | Description |
| --- | --- | --- |
| `primary` | `--mirio-primary` | Submit button, selected rating, progress bar, checked boxes and radios. |
| `primaryForeground` | `--mirio-primary-fg` | Text on primary, and the check or dot in a checked box. |
| `background` | `--mirio-bg` (and `--mirio-input-bg` unless `inputBackground` is set) | Surfaces inside the form. |
| `foreground` | `--mirio-fg` | Text. |
| `muted` | `--mirio-muted` | Hover, segmented track, success card. |
| `mutedForeground` | `--mirio-muted-fg` | Help text, placeholders, progress text. |
| `border` | `--mirio-border` | Control and card borders, unchecked boxes. |
| `ring` | `--mirio-ring` | Focus ring, checked choice border. |
| `error` | `--mirio-error` | Error text, invalid borders, required mark. |
| `inputBackground` | `--mirio-input-bg` | Control background, unchecked boxes. |
| `radius` | `--mirio-radius` | `'none'` 0, `'sm'` 0.25rem, `'md'` 0.5rem, `'lg'` 0.75rem, `'full'` 9999px, or any CSS length. |
| `font` | `--mirio-font` | Default `inherit`. |
| `colorScheme` | `data-mirio-color-scheme` | `'dark'` forces the built-in dark values, `'light'` forces light, `'auto'` follows `prefers-color-scheme`. Unset: follow a `.dark` / `[data-theme="dark"]` ancestor. |

Values are applied as inline variables on the form root, so they beat stylesheet values, including the dark ones.

### `size`
| Size | `--mirio-control-h` | `--mirio-text` | `--mirio-space` | `--mirio-gap` |
| --- | --- | --- | --- | --- |
| `sm` | 2.25rem | 14px | 1rem | 0.5rem |
| `md` (default) | 2.5rem | 15px | 1.25rem | 0.5rem |
| `lg` | 3rem | 16px | 1.5rem | 0.625rem |

Rendered as `data-mirio-size` on the root. `md` declares nothing, so your own `:root` values for these tokens keep working.

### `layout` (Form only)
| Key | Type | Description |
| --- | --- | --- |
| `columns` | `1 \| 2 \| 3` | Grid for the auto-rendered fields and `Page`. One column below 640px. |
| `full` | `string[]` | Field keys that span every column. `long_text`, `single_choice`, `multiple_choice` and `consent` always do; so does the page header. |

### `classNames`
Slots: `root`, `form`, `page`, `pageHeader`, `field`, `label`, `help`, `input` (Input, Textarea, Select, DatePicker), `option` (each choice row), `segment` (each YesNo button), `rating` (each rating button), `consent`, `error` (FieldError), `submit`, `button` (Back and Next), `progress`, `success`. Merged with tailwind-merge in this order: the component's defaults, the provider's slot, the form's slot, then the component's own `className`.

## Variants and states
<!-- preview: form-themed -->

```tsx
<Form schema={waitlist} client={mirio} theme={{ primary: '#2563eb', ring: '#2563eb', radius: 'full', border: '#bfdbfe', muted: '#eff6ff', mutedForeground: '#1d4ed8' }} />
```

<!-- preview: form-dark -->

```tsx
<div className="dark">   {/* or theme={{ colorScheme: 'dark' }} on the form */}
  <Form schema={waitlist} client={mirio} />
</div>
```

## Customization
For anything the props don't cover, use the variables directly (`:root`, `.dark`, or a wrapper), the `data-mirio` hooks from plain CSS, or the [headless](https://api.trymirio.com/docs/components/headless.md) layer. See [Styling](https://api.trymirio.com/docs/styling.md) for the five layers.

## Accessibility
Keep contrast when you change colors: `primaryForeground` on `primary` and `foreground` on `background` should reach 4.5:1. Focus rings use `ring`; don't set it to the background color. `colorScheme` also sets the CSS `color-scheme`, so native controls (date picker, scrollbars) match.

## Related
[Styling](https://api.trymirio.com/docs/styling.md), [Form](https://api.trymirio.com/docs/components/form.md), [MirioProvider](https://api.trymirio.com/docs/components/provider.md), [Components](https://api.trymirio.com/docs/components.md)

---

<!-- https://api.trymirio.com/docs/components/form.md -->

---
title: Form
description: The whole form from a schema: fields, submit, inline errors and the success state, with zero markup.
preview: form
---
# Form

`Form` takes a schema and a client and renders a finished form. With no children it renders every page itself; with children you compose the layout from the other components.

## Preview
<!-- preview: form -->

## Usage
```tsx
import { Form } from '@trymirio/mirio';
import { mirio } from '@/mirio/client';
import { waitlist } from '@/mirio/forms/waitlist';

export function Waitlist() {
  return <Form schema={waitlist} client={mirio} />;
}
```

One page renders the fields and a [Submit](https://api.trymirio.com/docs/components/submit.md) button. Several pages render [MultiStep](https://api.trymirio.com/docs/components/multi-step.md). After a successful submit the form is replaced by [Success](https://api.trymirio.com/docs/components/success.md), unless `settings.success` is a redirect or schedule, in which case the browser navigates.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `schema` | `FormSchema` | required | The schema from `defineForm`. |
| `client` | `MirioClient` | nearest `MirioProvider` | From `createClient` (`mirio/client.ts`). Throws a descriptive error when neither is present. |
| `onSuccess` | `(result: SubmissionResponse) => void` | — | Called with `{ id, status, success?, flags? }`. |
| `onError` | `(error: MirioError) => void` | — | Called with `{ code, message, hint?, fields?, status }`. |
| `initialValues` | `Record<string, unknown>` | — | Programmatic prefill, keyed by field key. Wins over `prefill.query` and `defaultValue`. |
| `children` | `ReactNode` | auto-render | Replaces the automatic layout. Use `Field`, `Submit`, `MultiStep` etc. inside. |
| `showSuccess` | `boolean` | `true` | Swap the form for `Success` after submit. |
| `requiredIndicator` | `ReactNode \| null` | nothing | What labels append to required fields. See [Label](https://api.trymirio.com/docs/components/label-help-error.md). |
| `optionalIndicator` | `ReactNode \| null` | muted "Optional" | What labels append to optional fields; `null` for nothing. |
| `theme` | `MirioTheme` | from `MirioProvider` | `primary`, `primaryForeground`, `background`, `foreground`, `muted`, `mutedForeground`, `border`, `ring`, `error`, `inputBackground`, `radius` (`'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` or a CSS length), `font`, `colorScheme` (`'light' \| 'dark' \| 'auto'`). Inline `--mirio-*` variables on the root; merged over the provider's per key. See [Theming](https://api.trymirio.com/docs/theming.md). |
| `size` | `'sm' \| 'md' \| 'lg'` | provider's, else `'md'` | Token bundle for control height, text size and spacing (`data-mirio-size`). |
| `layout` | `{ columns?: 1 \| 2 \| 3; full?: string[] }` | one column | Grid for the auto-rendered fields and `Page`. Long text, choices, consent and `full` keys span all columns; one column below 640px. |
| `classNames` | `Partial<Record<Slot, string>>` | — | Classes per part: `root`, `form`, `page`, `pageHeader`, `field`, `label`, `help`, `input`, `option`, `segment`, `rating`, `consent`, `error`, `submit`, `button`, `progress`, `success`. Merged after the provider's and before each component's own `className`. |
| `className` | `string` | `flex flex-col gap-mirio` | Merged onto the inner `<form>` (after `classNames.form`). |
| `rootClassName` | `string` | `font-mirio text-mirio-fg` | Merged onto the outer `[data-mirio-root]` wrapper (after `classNames.root`). |
| …`<form>` attributes | | | Everything else (`id`, `aria-label`, …) is spread on the `<form>`. `aria-label` defaults to `schema.name` unless you pass `aria-label` or `aria-labelledby`. |

Rendered structure:

```html
<div data-mirio-root data-mirio="form" data-slug="waitlist" data-status="idle|validating|submitting|success|error"
     data-mirio-size="md" [data-mirio-color-scheme="dark"] [style="--mirio-primary: …"]>
  <form novalidate aria-label="Waitlist">
    <div data-mirio="honeypot">…</div>            <!-- visually hidden, no CSS needed -->
    …fields…
    <div data-mirio="turnstile"></div>             <!-- only when a Turnstile site key is set -->
    <div role="alert" data-mirio="form-error" data-code="…"><p>message</p><p>hint</p></div>  <!-- only on a form-level error -->
  </form>
</div>
```

Form-level errors (network, `rate_limited`, `project_unclaimed`, `agents_blocked`, …) render the server's `message` and `hint` in `data-mirio="form-error"`. Field-level server errors (`validation_failed` with `fields`) go to the matching [FieldError](https://api.trymirio.com/docs/components/label-help-error.md) instead and focus moves to the first one.

## Variants and states

Composed layout: children replace the automatic rendering.

<!-- preview: form-composed -->

```tsx
import { Form, Field, Submit } from '@trymirio/mirio';

<Form schema={contact} client={mirio} className="gap-5">
  <div className="grid grid-cols-2 gap-4">
    <Field name="first_name" />
    <Field name="last_name" />
  </div>
  <Field name="email" />
  <Field name="message" />
  <Submit fullWidth={false} className="self-end" />
</Form>
```

Rethemed with the `theme` prop, same markup:

<!-- preview: form-themed -->

```tsx
<Form schema={waitlist} client={mirio} theme={{ primary: '#2563eb', ring: '#2563eb', radius: 'full', border: '#bfdbfe', muted: '#eff6ff', mutedForeground: '#1d4ed8' }} />
```

Dark, following the site: under a `.dark` (or `[data-theme="dark"]`) ancestor the built-in dark values apply. `theme={{ colorScheme: 'dark' }}` forces them on one form.

<!-- preview: form-dark -->

```tsx
<div className="dark">
  <Form schema={waitlist} client={mirio} />
</div>
```

Two columns and a larger size:

```tsx
<Form schema={demo} client={mirio} size="lg" layout={{ columns: 2, full: ['company_url'] }} />
```

Status is exposed as `data-status` on the wrapper, so `[data-mirio-root][data-status="submitting"]` can style the whole form while a request is in flight.

## Customization
- Variables the wrapper reads: `--mirio-font`, `--mirio-fg`, `--mirio-text`, `--mirio-space` (the gap between fields via `gap-mirio`), `--mirio-color-scheme`. Every child reads its own tokens; `theme`, `size` and `colorScheme` only change variables. See [Styling](https://api.trymirio.com/docs/styling.md) and [Theming](https://api.trymirio.com/docs/theming.md).
- `className` is merged with tailwind-merge, so `className="gap-2"` replaces the default `gap-mirio`; `className="grid grid-cols-2"` replaces `flex flex-col`.
- CSS hooks: `[data-mirio-root]` (scope), `[data-mirio="form"]`, `[data-mirio="form-error"]`, `[data-status="…"]`, `[data-slug="…"]`, `[data-mirio-size="…"]`, `[data-mirio-color-scheme="…"]`.
- To change the structure itself, compose children (`Field`, `Submit`, your own JSX) or build on the [headless](https://api.trymirio.com/docs/components/headless.md) hooks.

## Accessibility
- Renders a real `<form>` with `novalidate`: validation messages are Mirio's (inline, below each control), not the browser's bubbles. `aria-label` is the form name unless you label it yourself.
- Enter in a single-line input submits a single-page form, or advances to the next page in a multi-step form.
- On a failed submit, focus moves to the first invalid control (jumping to its page in a multi-step form). On a page change, focus moves to the page heading, or the first field when the page has no title.
- Form-level errors use `role="alert"`.
- The honeypot is `aria-hidden`, `tabindex="-1"` and off-screen; assistive technology never meets it.

## Related
[Field](https://api.trymirio.com/docs/components/field.md), [MultiStep](https://api.trymirio.com/docs/components/multi-step.md), [Success](https://api.trymirio.com/docs/components/success.md), [MirioProvider](https://api.trymirio.com/docs/components/provider.md), [Headless](https://api.trymirio.com/docs/components/headless.md), [Schema](https://api.trymirio.com/docs/schema.md), [Styling](https://api.trymirio.com/docs/styling.md), [Theming](https://api.trymirio.com/docs/theming.md)

---

<!-- https://api.trymirio.com/docs/components/field.md -->

---
title: Field
description: Label, help text, the right control for the field's type, and the inline error, from one `name`.
preview: field
---
# Field

`Field` renders one schema field completely: [Label](https://api.trymirio.com/docs/components/label-help-error.md), [Help](https://api.trymirio.com/docs/components/label-help-error.md), the control chosen by `field.type`, and [FieldError](https://api.trymirio.com/docs/components/label-help-error.md). It is what `Form` uses for every field when you give it no children.

## Preview
<!-- preview: field -->

## Usage
```tsx
import { Form, Field, FieldControl, Submit } from '@trymirio/mirio';

<Form schema={schema} client={mirio}>
  <Field name="name" />                       {/* label + help + control + error */}
  <Field name="seats" className="gap-1">      {/* children replace the control only */}
    <FieldControl name="seats" />
  </Field>
  <Submit />
</Form>
```

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. Throws if the key is not in the form's schema. |
| `children` | `ReactNode` | the control for `field.type` | Replaces the control slot only; label, help and error still render. Put your own input here using `useField(name).inputProps`. |
| `className` | `string` | `flex flex-col gap-1.5` | Merged onto the wrapper. |
| …`<div>` attributes | | | Spread on the wrapper. |

Rendered: `<div data-mirio="field" data-type="<field.type>">` containing `[data-mirio="label"]`, `[data-mirio="help"]` (when the schema has `help`), the control, and `[data-mirio="error"]` (when invalid).

`FieldControl` (`name` only) renders just the control. Which control a type gets:

| Field type | Control | data-mirio |
| --- | --- | --- |
| `short_text`, `email`, `phone`, `url`, `number` | [Input](https://api.trymirio.com/docs/components/input.md) | `input` |
| `long_text` | [Textarea](https://api.trymirio.com/docs/components/textarea.md) | `textarea` |
| `dropdown` | [Select](https://api.trymirio.com/docs/components/select.md) | `select` |
| `single_choice`, `multiple_choice` | [Choice](https://api.trymirio.com/docs/components/choice.md) | `choice` |
| `yes_no` | [YesNo](https://api.trymirio.com/docs/components/yes-no.md) | `yesno` |
| `rating` | [Rating](https://api.trymirio.com/docs/components/rating.md) | `rating` |
| `date` | [DatePicker](https://api.trymirio.com/docs/components/date-picker.md) | `date` |
| `consent` | [Consent](https://api.trymirio.com/docs/components/consent.md) (the row is its own label, so no `Label`; `Field` adds `Help` and `FieldError` under it) | `consent` |
| `hidden` | `<input type="hidden" data-type="hidden">` with no wrapper, label or error (`className` does not apply) | `hidden` |

Fields hidden by a `showWhen` condition render nothing at all (see [Conditional logic](https://api.trymirio.com/docs/conditional-logic.md)).

## Variants and states
The preview above has a required field and a number field: submit empty to see the error state, which sets `aria-invalid` on the control and renders `FieldError` below it. Typing clears the error for that field.

## Customization
- Spacing between label, control and error is the wrapper's `gap-1.5`; override with `className="gap-1"` (tailwind-merge drops the default).
- Target a type with CSS: `[data-mirio="field"][data-type="long_text"] { … }`.
- To change the structure (help below the control, label inside the control…), compose `Label`, `Help`, `FieldControl` and `FieldError` yourself, or build on `useField` from `@trymirio/mirio/headless`.

## Accessibility
`Field` wires the pieces: the label's `htmlFor` targets the control (`aria-labelledby` for radio groups), help and error ids go into the control's `aria-describedby`, required fields get `aria-required="true"` (not the native `required`, so Mirio's messages show instead of the browser's), and invalid fields get `aria-invalid="true"`.

## Related
[Form](https://api.trymirio.com/docs/components/form.md), [Label, Help, FieldError](https://api.trymirio.com/docs/components/label-help-error.md), [Headless: useField](https://api.trymirio.com/docs/components/headless.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/input.md -->

---
title: Input
description: The single-line text control for short_text, email, phone, url and number fields.
preview: input
---
# Input

A styled `<input>` bound to a field. `Field` renders it for `short_text`, `email`, `phone`, `url` and `number`; import it directly when you compose a field by hand.

## Preview
<!-- preview: input -->

## Usage
```tsx
// mirio/forms/newsletter.ts
import { defineForm } from '@trymirio/mirio/schema';

export const newsletter = defineForm({
  slug: 'newsletter',
  name: 'Newsletter',
  pages: [{ fields: [{ key: 'email', type: 'email', label: 'Work email', placeholder: 'you@company.com', autocomplete: 'email', required: true }] }],
});

// Rendered by <Form> automatically, or by hand:
import { Form, Field, Input, Submit } from '@trymirio/mirio';

<Form schema={newsletter} client={mirio}>
  <Field name="email" />          {/* label + help + <Input /> + error */}
  <Submit />
</Form>
```

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `type` | `string` | by field type | Overrides the HTML type: `email`→`email`, `phone`→`tel`, `url`→`url`, `number`→`text` (with `inputMode="decimal"`, or `numeric` when `integer: true`), otherwise `text`. |
| `className` | `string` | control classes | Merged onto the `<input>`. |
| …`<input>` attributes | | | Everything except `name`, `value`, `onChange` (those come from the field). `placeholder` defaults to the schema's `placeholder`. |

Renders `<input data-mirio="input">`. For a `hidden` field, `Input` renders `HiddenInput` (`<input type="hidden" data-mirio="hidden">`) instead.

`autocomplete` comes from the schema's `autocomplete`, else a default: `email` for email fields, `tel` for phone, `url` for url, and `name` / `given-name` / `family-name` / `organization` when a `short_text` key looks like one. Values are normalized on submit (trimmed, emails lower-cased, phones to E.164, URLs given `https://`), so the input itself never reformats what the visitor types.

## Variants and states
<!-- preview: input-states -->

```tsx
const fields = [
  { key: 'name', type: 'short_text', label: 'Full name', help: 'As it appears on your badge.', autocomplete: 'name', required: true },
  { key: 'website', type: 'url', label: 'Website', placeholder: 'acme.com', defaultValue: 'https://acme.com' },
  { key: 'seats', type: 'number', label: 'Seats', integer: true, min: 1, max: 500, required: true },
];
```

- **Required**: the label gets the required indicator and the input `aria-required`.
- **With help**: `help` renders below the label and is linked via `aria-describedby`.
- **Prefilled**: `defaultValue`, `prefill: { query }` (from the URL) or `initialValues` on `Form`.
- **Error**: after a failed submit, `aria-invalid="true"` turns the border red and `FieldError` appears. Format errors (bad email, bad URL) also show on blur; "required" waits for submit.
- **Disabled**: pass `disabled` when composing; the control dims and ignores input.

## Customization
- Reads `--mirio-bg`, `--mirio-fg`, `--mirio-border`, `--mirio-ring` (focus ring, 25 % alpha), `--mirio-error` (invalid border), `--mirio-muted-fg` (placeholder), `--mirio-radius`.
- `className` overrides resolve by utility: `className="h-12 text-base"` replaces `min-h-10 text-[15px]`; `className="rounded-none"` replaces `rounded-mirio`.
- CSS hook: `[data-mirio-root] [data-mirio="input"]`, plus `[aria-invalid="true"]` for the error state.
- `classNames={{ input: '…' }}` on `Form` or `MirioProvider` styles Input, Textarea, Select and DatePicker together; they share one set of control classes.

## Accessibility
Labelled by its `Label` through `htmlFor`; help and error text are in `aria-describedby`; `aria-required` and `aria-invalid` reflect state; `inputMode` gives phones the right keyboard for number fields. Enter submits (or advances a multi-step form).

## Related
[Field](https://api.trymirio.com/docs/components/field.md), [Textarea](https://api.trymirio.com/docs/components/textarea.md), [Label, Help, FieldError](https://api.trymirio.com/docs/components/label-help-error.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/textarea.md -->

---
title: Textarea
description: The multi-line control for long_text fields.
preview: textarea
---
# Textarea

A styled, vertically resizable `<textarea>`. `Field` renders it for `long_text`.

## Preview
<!-- preview: textarea -->

## Usage
```tsx
// { key: 'message', type: 'long_text', label: 'Message', help: 'A sentence or two is plenty.', maxLength: 500, required: true }
import { Form, Field, Textarea, Submit } from '@trymirio/mirio';

<Form schema={contact} client={mirio}>
  <Field name="message" />
  <Submit />
</Form>

// or inside a hand-built field:
<Textarea name="message" rows={6} />
```

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `rows` | `number` | `4` | Initial rows; the control also has `min-h-28` and `resize-y`. |
| `className` | `string` | control classes | Merged onto the `<textarea>`. |
| …`<textarea>` attributes | | | Everything except `name`, `value`, `onChange`. `placeholder` and `autocomplete` default to the schema's values. |

Renders `<textarea data-mirio="textarea">`. Long text is validated against `minLength`, `maxLength` (default 10 000) and `pattern` on submit; the server also counts links in text for spam scoring.

## Variants and states
Required, help, prefilled, error and disabled behave exactly like [Input](https://api.trymirio.com/docs/components/input.md#variants-and-states). Enter inserts a newline; it does not submit.

## Customization
- Same tokens as Input: `--mirio-bg`, `--mirio-fg`, `--mirio-border`, `--mirio-ring`, `--mirio-error`, `--mirio-muted-fg`, `--mirio-radius`.
- `className="min-h-40 resize-none"` replaces the default height and resize behavior.
- CSS hook: `[data-mirio-root] [data-mirio="textarea"]`.

## Accessibility
Same wiring as Input (`htmlFor`, `aria-describedby`, `aria-required`, `aria-invalid`).

## Related
[Input](https://api.trymirio.com/docs/components/input.md), [Field](https://api.trymirio.com/docs/components/field.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/select.md -->

---
title: Select
description: A styled native select for dropdown fields.
preview: select
---
# Select

A native `<select>` with the browser chrome removed and a chevron drawn in. `Field` renders it for `dropdown`. Native on purpose: it is accessible and works on every device without a custom listbox.

## Preview
<!-- preview: select -->

## Usage
```tsx
// { key: 'role', type: 'dropdown', label: 'Your role', options: ['Founder', 'Engineer', 'Designer', { value: 'other', label: 'Something else' }], required: true }
import { Form } from '@trymirio/mirio';

<Form schema={signup} client={mirio} />
```

Options are the schema's `options`: plain strings (value = label) or `{ value, label }` objects. The submitted value is the option `value`.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `className` | `string` | control classes + `appearance-none pr-10` | Merged onto the `<select>`. |
| …`<select>` attributes | | | Everything except `name`, `value`, `onChange`. `autocomplete` defaults to the schema's value. |

Renders `<div data-mirio="select-wrap" class="relative"><select data-mirio="select" …><option value="">…</option>…</select><svg/></div>`. `data-mirio="select"` and `className` are both on the `<select>`; the wrapper (`data-mirio="select-wrap"`) only positions the chevron. The first option is the placeholder (`field.placeholder`, default "Select an option"); while it is selected the `<select>` carries `data-placeholder` so its text can be muted.

## Variants and states
Required, error and disabled follow [Input](https://api.trymirio.com/docs/components/input.md#variants-and-states). Prefill with `defaultValue: 'Engineer'` (an option value).

## Customization
- Tokens: `--mirio-bg`, `--mirio-fg`, `--mirio-border`, `--mirio-ring`, `--mirio-error`, `--mirio-muted-fg` (placeholder and chevron), `--mirio-radius`.
- CSS hooks: `[data-mirio="select"]` (the control), `[data-mirio="select"][data-placeholder]` (nothing chosen yet), `[data-mirio="select-wrap"]` (wrapper, e.g. to move or recolor the chevron).
- For a custom listbox, build on `useField(name)` from `@trymirio/mirio/headless` and render your own control inside `Field`.

## Accessibility
Native semantics: the label's `htmlFor` targets the `<select>`, `aria-describedby`/`aria-required`/`aria-invalid` are set, and keyboard behavior is the platform's.

## Related
[Choice](https://api.trymirio.com/docs/components/choice.md), [Field](https://api.trymirio.com/docs/components/field.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/choice.md -->

---
title: Choice
description: A radio group for single_choice or a checkbox group for multiple_choice.
preview: choice
---
# Choice

Options as a vertical list of bordered cards, each with a radio or checkbox that Mirio draws (`.mirio-check`), so it follows the theme in light and dark. `Field` renders it for `single_choice` (one value) and `multiple_choice` (an array).

## Preview
<!-- preview: choice -->

## Usage
```tsx
// { key: 'timeline', type: 'single_choice', label: 'When do you want to start?', options: ['This month', 'This quarter', 'Just looking'], required: true }
import { Form } from '@trymirio/mirio';

<Form schema={demo} client={mirio} />

// by hand:
import { Choice } from '@trymirio/mirio';
<Choice name="timeline" optionClassName="py-2" />
```

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `className` | `string` | `flex flex-col gap-2` | Merged onto the group element. |
| `optionClassName` | `string` | option card classes | Merged onto every option `<label>`. |
| …`<div>` attributes | | | Spread on the group element (except `onChange`). |

Rendered structure:

```html
<div id="…" role="radiogroup|group" tabindex="-1" aria-labelledby="…-label" data-mirio="choice" [data-multiple]>
  <label for="…-0" data-mirio="option" [data-checked]>
    <input id="…-0" type="radio|checkbox" class="mirio-check" name="timeline" value="This month" />
    <span>This month</span>
  </label>
  …
</div>
```

The group element carries the field id, so error focus lands on it, and `data-multiple` is present for checkbox groups. `multiple_choice` honours `minSelected`/`maxSelected` on submit.

## Variants and states
Checkbox group:

<!-- preview: choice-multiple -->

```tsx
// { key: 'channels', type: 'multiple_choice', label: 'How did you hear about us?', help: 'Pick up to two.', options: ['Search', 'A friend', 'Social media', 'Newsletter'], maxSelected: 2 }
<Form schema={survey} client={mirio} />
```

- **Checked**: the option card gets `data-checked` and a `--mirio-ring` border (`has-[:checked]:border-mirio-ring`).
- **Hover**: cards tint with `--mirio-muted`.
- **Error**: the group gets `aria-invalid`; the message renders below the group.
- **Prefill**: `defaultValue: 'This month'` or, for multiple, `defaultValue: ['Search']`.

## Customization
- Tokens: `--mirio-border`, `--mirio-bg`, `--mirio-muted` (hover), `--mirio-ring` (checked border and focus ring), `--mirio-input-bg` and `--mirio-border` (the unchecked box), `--mirio-primary` and `--mirio-primary-fg` (the checked box and its check or dot), `--mirio-radius`.
- Horizontal options: `className="flex-row flex-wrap"`. Pills: `optionClassName="rounded-full py-1.5"`.
- CSS hooks: `[data-mirio="choice"]`, `[data-mirio="choice"][data-multiple]`, `[data-mirio="option"][data-checked]`, and the box itself: `.mirio-check`, `.mirio-check:checked`, `.mirio-check::before` (the check or dot). The box is centered on the first line of its label.
- The whole option card is the `<label>`, so clicking anywhere on it toggles the input.

## Accessibility
`role="radiogroup"` (single) or `role="group"` (multiple) labelled by the field label through `aria-labelledby`; help and error through `aria-describedby`; each option is a real `<input>` with its own `<label>`, so arrow keys (radios) and Space work natively and screen readers announce "1 of 3".

## Related
[Select](https://api.trymirio.com/docs/components/select.md), [YesNo](https://api.trymirio.com/docs/components/yes-no.md), [Field](https://api.trymirio.com/docs/components/field.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/yes-no.md -->

---
title: YesNo
description: Two segmented buttons with radio semantics for yes_no fields.
preview: yes-no
---
# YesNo

A segmented control with two options. The value is a boolean; the words come from the schema's `options` (exactly two, yes first) when set, otherwise "Yes" and "No". `Field` renders it for `yes_no`.

## Preview
<!-- preview: yes-no -->

## Usage
```tsx
// { key: 'has_team', type: 'yes_no', label: 'Do you work with a team?', options: ['Yes, a team', 'Just me'], required: true }
import { Form } from '@trymirio/mirio';

<Form schema={intake} client={mirio} />

// by hand, overriding the words for this render only:
import { YesNo } from '@trymirio/mirio';
<YesNo name="has_team" yesLabel="Team" noLabel="Solo" />
```

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `yesLabel` | `string` | `options[0]` label, else `"Yes"` | Overrides the text of the `true` segment. |
| `noLabel` | `string` | `options[1]` label, else `"No"` | Overrides the text of the `false` segment. |
| `className` | `string` | segmented group classes (`inline-flex w-full max-w-xs …`) | Merged onto the group element. |
| …`<div>` attributes | | | Spread on the group element (except `onChange`). |

Rendered: `<div id role="radiogroup" tabindex="-1" aria-labelledby data-mirio="yesno">` with two `<button type="button" role="radio" aria-checked data-value="true|false">`.

A `yes_no` field that is `required` must be answered; an unanswered optional field submits `null`. (For "must be yes", use a `consent` field.)

## Variants and states
- **Checked**: the segment lifts onto `--mirio-bg` with a small shadow; the other stays muted.
- **Error**: `aria-invalid` on the group plus the message below.
- **Prefill**: `defaultValue: true`.

## Customization
- Tokens: `--mirio-muted` (track), `--mirio-bg` (selected segment), `--mirio-fg` / `--mirio-muted-fg` (text), `--mirio-border`, `--mirio-ring`, `--mirio-radius` (segments use `radius - 2px`).
- `className="max-w-none"` makes it full width; `classNames={{ segment: '…' }}` on `Form` styles each button.
- CSS hooks: `[data-mirio="yesno"]`, `[data-mirio="yesno"] [role="radio"][aria-checked="true"]`, `[data-value="true"]`.

## Accessibility
Radio semantics without native radios: `role="radiogroup"` + `role="radio"`/`aria-checked`, roving `tabindex` (one segment is tabbable), and Left/Right/Up/Down/Home/End move the selection and focus.

## Related
[Choice](https://api.trymirio.com/docs/components/choice.md), [Consent](https://api.trymirio.com/docs/components/consent.md), [Rating](https://api.trymirio.com/docs/components/rating.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/rating.md -->

---
title: Rating
description: Numbered buttons from 1 to max with radio semantics for rating fields.
preview: rating
---
# Rating

A row of square buttons from `min` (default 1, may be 0) through `max` (default 5, between 2 and 10). The value is an integer. `Field` renders it for `rating`.

## Preview
<!-- preview: rating -->

## Usage
```tsx
// { key: 'score', type: 'rating', label: 'How likely are you to recommend us?', max: 5, required: true }
import { Form } from '@trymirio/mirio';

<Form schema={feedback} client={mirio} />

// by hand:
import { Rating } from '@trymirio/mirio';
<Rating name="score" buttonClassName="rounded-full" />
```

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. The range comes from the schema: `field.min` (default 1) to `field.max` (default 5). |
| `className` | `string` | `flex flex-wrap gap-2` | Merged onto the group element. |
| `buttonClassName` | `string` | rating button classes (`size-10 …`) | Merged onto every button. |
| …`<div>` attributes | | | Spread on the group element (except `onChange`). |

Rendered: `<div id role="radiogroup" tabindex="-1" aria-labelledby data-mirio="rating">` with one `<button type="button" role="radio" aria-checked aria-label="3 of 5" data-value="3">3</button>` per step. Only the chosen number is highlighted (it is a scale, not stars).

## Variants and states
- **Checked**: `--mirio-primary` background with `--mirio-primary-fg` text.
- **Hover**: `--mirio-muted`.
- **Error**: `aria-invalid` on the group, message below.
- **Prefill**: `defaultValue: 4`.

## Customization
- Tokens: `--mirio-bg`, `--mirio-fg`, `--mirio-border`, `--mirio-muted`, `--mirio-primary`, `--mirio-primary-fg`, `--mirio-ring`, `--mirio-radius`.
- Larger: `buttonClassName="size-12 text-base"`. A 0–10 scale wraps because the group is `flex-wrap`; use `className="flex-nowrap gap-1"` to keep it on one line.
- To render stars or emoji, build on `useField(name)` and keep the radio semantics below.
- CSS hooks: `[data-mirio="rating"]`, `[data-mirio="rating"] [aria-checked="true"]`, `[data-value="5"]`.

## Accessibility
`role="radiogroup"` labelled by the field label; each step is `role="radio"` with `aria-checked` and an `aria-label` like "3 of 5"; roving `tabindex`; arrow keys and Home/End move selection and focus.

## Related
[YesNo](https://api.trymirio.com/docs/components/yes-no.md), [Choice](https://api.trymirio.com/docs/components/choice.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/date-picker.md -->

---
title: DatePicker
description: A styled native date input for date fields.
preview: date-picker
---
# DatePicker

`<input type="date">` with Mirio's control styling. `Field` renders it for `date`. No custom calendar: the native one is accessible, localized and works on phones.

## Preview
<!-- preview: date-picker -->

## Usage
```tsx
// { key: 'preferred_date', type: 'date', label: 'Preferred date', min: '2026-01-01' }
import { Form } from '@trymirio/mirio';

<Form schema={booking} client={mirio} />
```

The value is an ISO date string (`YYYY-MM-DD`). `min`/`max` on the field are ISO strings and are enforced both as native attributes and on submit.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `className` | `string` | control classes + `appearance-none` | Merged onto the `<input>`. |
| …`<input>` attributes | | | Everything except `name`, `value`, `onChange`, `type`. `min`, `max` and `autocomplete` default to the schema's values. |

Renders `<input type="date" data-mirio="date">`.

## Variants and states
Required, error, disabled as for [Input](https://api.trymirio.com/docs/components/input.md#variants-and-states). Prefill with `defaultValue: '2026-03-01'` or `prefill: { query: 'date' }`.

## Customization
- Same tokens as Input. The picker icon and popup are the browser's; `color-scheme: dark` on a dark wrapper switches them.
- CSS hook: `[data-mirio="date"]`.
- For a custom calendar, use `useField(name)` from `@trymirio/mirio/headless` and set an ISO string with `setValue`.

## Accessibility
Native date input semantics and keyboard handling; labelled and described like every other control.

## Related
[Input](https://api.trymirio.com/docs/components/input.md), [Field](https://api.trymirio.com/docs/components/field.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/consent.md -->

---
title: Consent
description: A checkbox with its label inline, for consent fields that must be ticked.
preview: consent
---
# Consent

A checkbox whose label sits next to it. `Field` renders it for `consent` followed by [Help](https://api.trymirio.com/docs/components/label-help-error.md) and [FieldError](https://api.trymirio.com/docs/components/label-help-error.md) under the row; there is no separate `Label`, by design, because the label is the clickable row.

## Preview
<!-- preview: consent -->

## Usage
```tsx
// { key: 'consent', type: 'consent', label: 'Email me when Acme launches', help: 'One email, no newsletters.', required: true }
import { Form } from '@trymirio/mirio';

<Form schema={waitlist} client={mirio} />

// by hand, with richer label content:
import { Consent } from '@trymirio/mirio';
<Consent name="consent">
  I agree to the <a href="/terms" className="underline">terms</a>
</Consent>
```

A `required` consent must be `true` to submit ("You need to agree to continue"); an optional one submits `false` when unticked.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `children` | `ReactNode` | `field.label` | Replaces the label text. Help comes from `<Help name>`, which `Field` renders for you. |
| `className` | `string` | `flex items-start gap-3 text-sm …` | Merged onto the `<label>`. |
| …`<label>` attributes | | | Spread on the `<label>` (except `onChange`). |

Rendered: `<label for data-mirio="consent"><input type="checkbox" …/><span>label</span></label>`. The checkbox carries the field's `id`, `aria-required`, `aria-invalid` and `aria-describedby` (pointing at the `Help` and `FieldError` elements that `Field` renders under the row, indented to align with the text).

## Variants and states
- **Required**: the indicator from `requiredIndicator` (none by default) is appended to the label text; an unticked required box shows its error on submit.
- **Error**: unticked on submit shows "You need to agree to continue" under the row (indented to align with the text).
- **Prefill**: `defaultValue: true` pre-ticks it; think twice before doing that for consent.

## Customization
- Tokens: `--mirio-input-bg` and `--mirio-border` (the unticked box), `--mirio-primary` and `--mirio-primary-fg` (the ticked box and its check), `--mirio-fg`, `--mirio-error`; help uses `--mirio-muted-fg` through `Help`.
- The box is centered on the label's first line; `className="items-center"` centres it on the whole label instead.
- CSS hooks: `[data-mirio="consent"]`, `[data-mirio="consent"] .mirio-check` (Mirio draws the box, so it follows the theme; `::before` is the check).

## Accessibility
A real `<label>` wraps the checkbox, so the whole row is clickable and announced as one control; help and error are linked with `aria-describedby` and the error is a live region; required and invalid states are exposed with `aria-required`/`aria-invalid`.

## Related
[YesNo](https://api.trymirio.com/docs/components/yes-no.md), [Field](https://api.trymirio.com/docs/components/field.md), [Label, Help, FieldError](https://api.trymirio.com/docs/components/label-help-error.md), [Schema: field types](https://api.trymirio.com/docs/schema.md)

---

<!-- https://api.trymirio.com/docs/components/submit.md -->

---
title: Submit
description: The submit button, labelled from settings.submitLabel, with a loading state.
preview: submit
---
# Submit

A primary button of `type="submit"`. Its label comes from `settings.submitLabel` (default "Submit"); while the form validates or posts it is disabled, shows a spinner and sets `aria-busy`.

## Preview
<!-- preview: submit -->

## Usage
```tsx
// settings: { submitLabel: 'Join the waitlist' }
import { Form, Field, Submit } from '@trymirio/mirio';

<Form schema={waitlist} client={mirio}>
  <Field name="email" />
  <Submit />                       {/* label from settings.submitLabel, default "Submit" */}
</Form>

<Submit fullWidth={false}>Count me in</Submit>   {/* children override the label */}
```

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `settings.submitLabel ?? "Submit"` | The label. |
| `fullWidth` | `boolean` | `true` | Stretch to the form width (`w-full`); `false` renders `w-auto`. `MultiStep` passes `false` so Submit sits next to Back. |
| `disabled` | `boolean` | `false` | Also disabled automatically while submitting. |
| `variant` | `'primary' \| 'secondary'` | `'primary'` | From `Button`. |
| `className` | `string` | button classes + `w-full`/`w-auto` | Merged onto the `<button>`. |
| …`Button` props | | | Everything from `Button` except `type` and `children`. |

Renders `<button type="submit" data-mirio="submit" data-variant="primary" [aria-busy="true"]>` with `[data-mirio="spinner"]` while busy. The same `Button` component (`data-mirio="button"`) is exported for Back/Next and your own buttons.

## Variants and states
- **Idle**: `--mirio-primary` background, `--mirio-primary-fg` text.
- **Submitting**: spinner, `disabled`, `aria-busy="true"`, 60 % opacity.
- **Inside MultiStep**: shown only on the last visible page, with `fullWidth={false}` and `min-w-28`.

## Customization
- Tokens: `--mirio-primary`, `--mirio-primary-fg`, `--mirio-ring` (focus ring), `--mirio-bg` (ring offset), `--mirio-radius`.
- `fullWidth={false}` undoes the full width; `className="bg-emerald-600 hover:bg-emerald-700"` replaces the primary background because tailwind-merge resolves the conflict.
- CSS hooks: `[data-mirio="submit"]`, `[data-mirio="submit"][aria-busy="true"]`, `[data-mirio="button"][data-variant="secondary"]`.

## Accessibility
A native submit button: Enter and Space activate it, Enter inside an input submits through it. `aria-busy` announces the in-flight state; `disabled` prevents double submits (the hook also ignores repeat submits).

## Related
[Form](https://api.trymirio.com/docs/components/form.md), [MultiStep](https://api.trymirio.com/docs/components/multi-step.md), [Success](https://api.trymirio.com/docs/components/success.md)

---

<!-- https://api.trymirio.com/docs/components/success.md -->

---
title: Success
description: The thank-you card rendered from settings.success after a submission.
preview: success
---
# Success

A centred card with a filled check mark, a title and a message. `Form` swaps the `<form>` for it after a successful submit when `settings.success` is a message (or unset). Redirect and schedule successes navigate instead.

## Preview
<!-- preview: success -->

## Usage
```tsx
// settings: { success: { type: 'message', title: 'You are on the list', message: 'We will email you once when we launch.' } }
<Form schema={waitlist} client={mirio} />   // swaps to <Success /> after a successful submit

// Your own success UI instead:
<Form schema={waitlist} client={mirio} showSuccess={false} onSuccess={(res) => router.push(`/thanks?id=${res.id}`)} />

// Or the card with custom copy, inside a composed form:
import { Success } from '@trymirio/mirio';
<Success title="Got it">We reply within a day.</Success>
```

The text comes from the schema's `settings.success` (the code the visitor's browser runs); the server's echoed `success` is used only when the schema has none.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | `success.title ?? "Thank you"` | Heading. |
| `children` | `ReactNode` | `success.message ?? "Your response has been recorded."` | Body text. |
| `className` | `string` | card classes | Merged onto the root. |
| …`<div>` attributes | | | Spread on the root (except `title`). |

Renders `<div role="status" data-mirio="success"><svg/><h3>title</h3><p>message</p></div>`. It must be rendered inside a `Form` or `FormProvider` (it reads the form's `success`).

## Variants and states
- **Message**: shown as above.
- **Redirect / schedule**: not shown; the hook resolves the URL (with prefill and `utm_*` passthrough) and navigates. Custom UIs can read `successUrl` from `useMirioForm` and render a link instead.
- **`showSuccess={false}`**: `Form` keeps rendering the form; handle `onSuccess` yourself.

## Customization
- Tokens: `--mirio-muted` (card background), `--mirio-border`, `--mirio-primary` (the check mark's disc) and `--mirio-primary-fg` (the check), `--mirio-fg`, `--mirio-muted-fg`, `--mirio-radius`.
- `className="bg-transparent border-0 py-6 text-left items-start"` turns the card into plain text.
- CSS hooks: `[data-mirio="success"]`, or `[data-mirio-root][data-status="success"]` on the wrapper.

## Accessibility
`role="status"` announces the result politely when it appears. The check mark is `aria-hidden`. When it replaces the form, the card takes keyboard focus, and if it's off-screen it scrolls into view with its top at the top of the window.

**Fixed headers:** with a fixed or sticky nav, give the scroll an offset so the card lands below it, e.g. `html { scroll-padding-top: 5rem; }` (your nav's height plus a little), or only for the card: `[data-mirio="success"] { scroll-margin-top: 5rem; }`.

## Related
[Form](https://api.trymirio.com/docs/components/form.md), [Submit](https://api.trymirio.com/docs/components/submit.md), [Schema: settings](https://api.trymirio.com/docs/schema.md), [Headless: successUrl](https://api.trymirio.com/docs/components/headless.md)

---

<!-- https://api.trymirio.com/docs/components/multi-step.md -->

---
title: MultiStep
description: One page at a time with a progress line, Back and Next, and Submit on the last page. Covers MultiStep, Page and Progress.
preview: multi-step
---
# MultiStep

A schema with more than one page renders as a multi-step form: [Progress](#progress), the current [Page](#page), Back/Next buttons, and Submit on the last page. Progress is saved to Mirio after each completed step as a partial submission.

## Preview
<!-- preview: multi-step -->

## Usage
```tsx
// A schema with several pages renders as MultiStep automatically:
<Form schema={demo} client={mirio} />

// The same, composed:
import { Form, MultiStep, Page, Progress, Field } from '@trymirio/mirio';

<Form schema={demo} client={mirio}>
  <Progress />
  <MultiStep notice="We save your progress after each step." />
</Form>

// Custom content per step (children replace the current page's fields):
function Steps() {
  const { pageIndex } = useForm();
  return (
    <MultiStep>
      {pageIndex === 0 && <><Field name="name" /><Field name="email" /></>}
      {pageIndex === 1 && <Field name="timeline" />}
    </MultiStep>
  );
}
```

Pages with a `showWhen` condition that is false, or whose fields are all hidden, are skipped by Next/Back and left out of the step count. See [Conditional logic](https://api.trymirio.com/docs/conditional-logic.md).

## Props

### MultiStep
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nextLabel` | `ReactNode` | `"Next"` | Label of the Next button. |
| `backLabel` | `ReactNode` | `"Back"` | Label of the Back button. |
| `notice` | `ReactNode \| null` | none | A line under the buttons, such as `"We save your progress after each step."` |
| `children` | `ReactNode` | the current page's fields | Rendered inside the current `Page` instead of its fields. |
| `showProgress` | `boolean` | `true` | Render the progress line at the top. |
| `progress` | `ReactNode` | `<Progress />` | Replaces the built-in progress element (e.g. `<Progress label={(s, c) => `${s}/${c}`} />` or your own stepper). |
| `className` | `string` | `flex flex-col gap-mirio` | Merged onto the root. |
| …`<div>` attributes | | | Spread on the root. |

Renders `<div data-mirio="multistep">` containing the progress element, the current `Page`, `<div data-mirio="nav">` with `[data-mirio="back"]` (secondary `Button`, hidden on the first visible page) and `[data-mirio="next"]` (a `type="submit"` button, so Enter advances) or [Submit](https://api.trymirio.com/docs/components/submit.md) with `fullWidth={false}` on the last visible page, and `<p data-mirio="notice">` when there's a `notice`.

### Page
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` | the current page | Which page of `schema.pages` to render. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | Element used for the page title. |
| `children` | `ReactNode` | the page's visible fields as `Field`s | Replaces the fields. |
| `className` | `string` | `flex flex-col gap-mirio` | Merged onto the root. |
| …`<div>` attributes | | | Spread on the root. |

Renders `<div data-mirio="page">` with an optional `<div data-mirio="page-header">` holding `<h2 id tabindex="-1">title</h2>` (or `h3`/`h4` per `headingLevel`) and a description, then the fields. Renders nothing when the page is hidden.

### Progress
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `(step: number, count: number) => string` | `` `Step ${step} of ${count}` `` | Custom text; `step` is 1-based and both count visible pages only. |
| `className` | `string` | `flex items-center gap-3 text-sm text-mirio-muted-fg` | Merged onto the root. |
| …`<div>` attributes | | | Spread on the root. |

Renders `<div data-mirio="progress"><span>Step 2 of 3</span><div role="progressbar" aria-valuemin="1" aria-valuemax="3" aria-valuenow="2" aria-valuetext="Step 2 of 3"><div style="width: 66%"/></div></div>`.

## Variants and states
- **First page**: no Back button (a spacer keeps Next on the right).
- **Last visible page**: Submit replaces Next.
- **Validation**: Next validates only the current page's visible fields; on failure the first invalid control is focused and the page stays. Submit validates every visible field and jumps to the first page with an error.
- **Saving**: after each successful Next, the completed pages are sent as a partial (`status: 'partial'`, same session id kept in `sessionStorage`); the final submit completes the same record. Nothing is saved on keystrokes.

## Customization
- Tokens: `--mirio-space` (gaps), `--mirio-muted` (progress track), `--mirio-primary` (progress bar), `--mirio-muted-fg` (progress text and notice), plus the button tokens.
- `notice="…"` adds a line under the buttons; `showProgress={false}` removes the progress line; `progress={<Progress label={(s, c) => `${s}/${c}`} />}` keeps it but shortens the text.
- CSS hooks: `[data-mirio="multistep"]`, `[data-mirio="progress"]`, `[data-mirio="page"]`, `[data-mirio="page-header"]`, `[data-mirio="nav"]`, `[data-mirio="back"]`, `[data-mirio="next"]`, `[data-mirio="notice"]`.
- For a wizard with a sidebar or horizontal steps, use `usePage()` and `useForm().visiblePages` from the headless layer and render your own chrome around `Page`.

## Accessibility
On page change focus moves to the page heading (`tabindex="-1"`) or to the first field when the page has no title, so screen readers announce the new step. Next is a submit button so Enter advances; Back is `type="button"`. The progress bar exposes `role="progressbar"` with min/max/now and a text value.

## Related
[Form](https://api.trymirio.com/docs/components/form.md), [Submit](https://api.trymirio.com/docs/components/submit.md), [Conditional logic](https://api.trymirio.com/docs/conditional-logic.md), [Partial submissions](https://api.trymirio.com/docs/partials.md), [Headless: usePage](https://api.trymirio.com/docs/components/headless.md)

---

<!-- https://api.trymirio.com/docs/components/label-help-error.md -->

---
title: Label, Help, FieldError
description: The three text pieces around a control, usable on their own when you compose a field by hand.
preview: label-help-error
---
# Label, Help, FieldError

`Field` renders these for you. Import them when you assemble a field yourself, or to change the words without touching the schema.

## Preview
<!-- preview: label-help-error -->

## Usage
```tsx
import { Form, Label, Help, FieldControl, FieldError, Submit } from '@trymirio/mirio';

<Form schema={schema} client={mirio}>
  <div className="flex flex-col gap-1.5">
    <Label name="company">Company name</Label>   {/* children override the schema label */}
    <Help name="company" />
    <FieldControl name="company" />
    <FieldError name="company" />
  </div>
  <Submit />
</Form>
```

## Props

### Label
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `children` | `ReactNode` | `field.label` | Replaces the label text. |
| `requiredIndicator` | `ReactNode \| null` | from `Form`/`MirioProvider`, else nothing | What to append when `field.required`. |
| `optionalIndicator` | `ReactNode \| null` | from `Form`/`MirioProvider`, else a small muted "Optional" | What to append when the field isn't required; `null` renders nothing. |
| `className` | `string` | `text-sm font-medium leading-none text-mirio-fg` | Merged onto the element. |
| …`<label>` attributes | | | Spread on the `<label>`. |

Renders `<label for="<control id>" id="<label id>" data-mirio="label">`. For grouped controls (`single_choice`, `multiple_choice`, `yes_no`, `rating`) it renders a `<span id data-mirio="label">` instead, because the group is labelled through `aria-labelledby` rather than `for`.

### Help
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `children` | `ReactNode` | `field.help` | Replaces the help text. Renders nothing when there is none. |
| `className` | `string` | `text-sm text-mirio-muted-fg` | Merged onto the `<p>`. |
| …`<p>` attributes | | | Spread on the `<p>`. |

Renders `<p id="<help id>" data-mirio="help">`; the id is in the control's `aria-describedby`. `Field` places it under the label, and under the checkbox row for `consent` fields.

### FieldError
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | The field key. |
| `className` | `string` | `text-sm text-mirio-error` | Merged onto the `<p>`. |
| …`<p>` attributes | | | Spread on the `<p>`. |

Renders `<p id="<error id>" role="alert" data-mirio="error">message</p>` while the field has an error, nothing otherwise. Messages come from Mirio's validator (client and server use the same one), e.g. "This field is required", "Enter a valid email address", "Choose at most 2".

## Variants and states
Required and optional marks (since 0.1.3): by default optional fields get a small, muted "Optional" after the label and required fields get no mark. Most fields on a short form are required, so a mark on each says little; screen readers hear "Optional" with the label, and required controls carry `aria-required`. Set either mark once for every form, or per label:

<!-- preview: required-indicator -->

```tsx
<Form schema={schema} client={mirio}>            // the default
  <Field name="email" />
</Form>

<MirioProvider
  client={mirio}
  requiredIndicator={<span aria-hidden className="ml-0.5 text-mirio-error">*</span>}   // asterisks instead
  optionalIndicator={null}
>
  <Form schema={schema}>…</Form>
</MirioProvider>

<Label name="company" optionalIndicator={null}>Company</Label>   // one label
```

Resolution order for each: the `Label` prop, then the nearest `Form`/`MirioProvider` that set one, then the default (nothing for required, "Optional" for optional). A required `consent` checkbox uses `requiredIndicator`; an optional one has no mark.

## Customization
- Tokens: `--mirio-fg` (label), `--mirio-muted-fg` (help and the "Optional" mark), `--mirio-error` (error).
- `className="text-base font-semibold"` on `Label` replaces the size and weight. `FieldError` with `className="text-xs"` shrinks the message.
- CSS hooks: `[data-mirio="label"]`, `[data-mirio="help"]`, `[data-mirio="error"]`.
- Label and help text are part of the schema (and its hash): changing them is a schema change that `mirio push` records as a new version; overriding with `children` is a display-only change.

## Accessibility
`Label` targets the control with `for` (or labels a group through `aria-labelledby`). `Help` and `FieldError` ids are joined into the control's `aria-describedby`, so screen readers read help on focus and the error with the control. `FieldError` is a live region (`role="alert"`), so a new message is announced when it appears, and Mirio also moves focus to the first invalid control after a failed submit. The default `*` is `aria-hidden`; required state is conveyed by `aria-required` on the control.

## Related
[Field](https://api.trymirio.com/docs/components/field.md), [MirioProvider](https://api.trymirio.com/docs/components/provider.md), [Consent](https://api.trymirio.com/docs/components/consent.md), [Headless: useField](https://api.trymirio.com/docs/components/headless.md)

---

<!-- https://api.trymirio.com/docs/components/provider.md -->

---
title: MirioProvider
description: Provide the client and display options once so every Form can omit them.
---
# MirioProvider

Wrap your app (or a layout) once with `MirioProvider` and every `Form` below it finds the client through context. It also carries site-wide display options: `theme`, `size`, `classNames`, `requiredIndicator` and `optionalIndicator`.

## Preview
`MirioProvider` renders nothing visible. See the [required indicator](https://api.trymirio.com/docs/components/label-help-error.md#variants-and-states) preview for its effect.

## Usage
```tsx
// app/providers.tsx (Next.js app router: a client component, because the client holds functions)
'use client';
import { MirioProvider } from '@trymirio/mirio';
import { mirio } from '@/mirio/client';

export function Providers({ children }: { children: React.ReactNode }) {
  return <MirioProvider client={mirio}>{children}</MirioProvider>;
}

// any page, even a server component: the schema is plain data
import { Form } from '@trymirio/mirio';
import { waitlist } from '@/mirio/forms/waitlist';

export default function Page() {
  return <Form schema={waitlist} />;
}
```

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `client` | `MirioClient` | inherited from a parent provider | From `createClient`. Optional when nesting: a provider without `client` keeps the parent's. |
| `requiredIndicator` | `ReactNode \| null` | inherited, else nothing | What `Label` appends to required fields. |
| `optionalIndicator` | `ReactNode \| null` | inherited, else muted "Optional" | What `Label` appends to optional fields. `null` for nothing. |
| `theme` | `MirioTheme` | inherited | Colors, `radius`, `font`, `colorScheme` for every form below; merged per key with a parent provider's and with each form's (the form wins). See [Theming](https://api.trymirio.com/docs/theming.md). |
| `size` | `'sm' \| 'md' \| 'lg'` | inherited, else `'md'` | Default size for every form below; a form's `size` wins. |
| `classNames` | `Partial<Record<Slot, string>>` | inherited | Classes per part for every form below. Per slot, the parent's, this provider's and the form's classes are all kept, in that order, then the component's own `className`. |
| `children` | `ReactNode` | — | |

Renders no DOM element and has no `className` or `data-mirio`.

Hooks: `useMirioClient()` returns the nearest client or `null`; `useFormOptions()` returns the merged display options; `useSlot(slot)` returns the merged classes for one slot (for your own components). `layout` is a `Form` prop only. `Form` scopes its own options (merged over the provider's) to its subtree.

## Variants and states
Nesting merges: an inner provider can change one option and keep the rest.

```tsx
<MirioProvider client={mirio} theme={{ primary: 'var(--brand)', radius: 'lg' }} size="sm" classNames={{ label: 'uppercase tracking-wide' }}>
  <Form schema={waitlist} />                                    {/* brand primary, lg radius, sm, uppercase labels */}
  <Form schema={demo} size="md" theme={{ colorScheme: 'dark' }} /> {/* same, but md and dark */}
</MirioProvider>
```


```tsx
<MirioProvider client={mirio} optionalIndicator={<span> (optional)</span>}>
  …most forms…
  <MirioProvider requiredIndicator={<span> (required)</span>} optionalIndicator={null}>
    <Form schema={application} />   {/* same client, different marks */}
  </MirioProvider>
</MirioProvider>
```

A `Form` with its own `client` prop ignores the context client; `requiredIndicator` on `Form` overrides the provider's for that form only.

## Customization
Renders no DOM. `theme` becomes inline variables on each `Form` root; you can also set `--mirio-*` variables on `:root` or a wrapper (see [Styling](https://api.trymirio.com/docs/styling.md)).

## Accessibility
No effect on its own; see [Label](https://api.trymirio.com/docs/components/label-help-error.md) for how the required indicator is exposed (`aria-hidden` mark, `aria-required` on the control).

## Related
[Form](https://api.trymirio.com/docs/components/form.md), [Theming](https://api.trymirio.com/docs/theming.md), [Label, Help, FieldError](https://api.trymirio.com/docs/components/label-help-error.md), [Client SDK](https://api.trymirio.com/docs/api.md)

---

<!-- https://api.trymirio.com/docs/components/headless.md -->

---
title: Headless
description: Behavior and accessibility with no markup: useMirioForm, FormProvider, useForm, useField, usePage, useFormStatus, Honeypot, Turnstile.
---
# Headless

`@trymirio/mirio/headless` is what the styled components are built on. Use it to render a form with your own elements and classes while keeping Mirio's validation, focus management, conditional logic, partial saves, retries and spam signals.

## Preview
No styled preview: the output is whatever markup you write. The example site's `/custom` page is a complete headless form.

## Usage
```tsx
import { useMirioForm, FormProvider, useField, useForm, Honeypot } from '@trymirio/mirio/headless';
import { mirio } from '@/mirio/client';
import { feedback } from '@/mirio/forms/feedback';

function TextField({ name }: { name: string }) {
  const { field, visible, value, setValue, error, inputProps, errorId } = useField(name);
  if (!visible) return null;
  return (
    <div>
      <label htmlFor={inputProps.id}>{field.label}</label>
      <input {...inputProps} value={(value as string) ?? ''} onChange={(e) => setValue(e.target.value)} />
      {error ? <p id={errorId}>{error}</p> : null}
    </div>
  );
}

function SubmitButton() {
  const { status } = useForm();
  return <button type="submit" disabled={status === 'submitting'}>Send</button>;
}

export function Feedback() {
  const form = useMirioForm(feedback, { client: mirio });
  if (form.status === 'success') return <p>Thanks! Submission {form.result?.id} is in.</p>;
  return (
    <FormProvider form={form}>
      <form {...form.formProps}>
        <Honeypot />
        <TextField name="comments" />
        <TextField name="email" />
        <SubmitButton />
      </form>
    </FormProvider>
  );
}
```

Spread `form.formProps` on a real `<form>`: it wires `onSubmit` (Enter submits a single-page form or advances a multi-step one) and `noValidate`.

## Props

### `useMirioForm(schema, options)`
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `client` | `MirioClient` | required | From `createClient`. |
| `onSuccess` | `(result: SubmissionResponse) => void` | — | After a successful submit. |
| `onError` | `(error: MirioError) => void` | — | After a failed submit (`code`, `message`, `hint`, `fields`, `status`). |
| `initialValues` | `Record<string, unknown>` | — | Programmatic prefill; wins over `prefill.query` and `defaultValue`. |
| `sessionId` | `string` | generated, kept in `sessionStorage` | Fixed session id for partial saves. |
| `actor` | `Actor` | the client's `actor` | `{ type: 'human' \| 'agent', name?, onBehalfOf? }`, sent as `meta.actor`. |
| `navigate` | `(url: string) => void` | `window.location.assign` | How to follow a redirect/schedule success. |

Everything the hook returns:

| Key | Type | Description |
| --- | --- | --- |
| `schema`, `client` | | What you passed in. |
| `formId` | `string` | Stable, SSR-safe prefix for element ids. |
| `values` | `Record<string, unknown>` | Current values of visible fields (hidden fields are pruned). |
| `errors` | `Record<string, string>` | Message per invalid field key. |
| `touched` | `Record<string, boolean>` | Fields that were blurred or validated. |
| `pageIndex` | `number` | Index into `schema.pages` of the page being shown. |
| `pageCount` | `number` | Number of visible pages. |
| `stepIndex` | `number` | 0-based position of the current page among visible pages ("Step `stepIndex + 1` of `pageCount`"). |
| `visiblePages` | `number[]` | Indexes of the pages that are visible right now. |
| `visibleKeys` | `Set<string>` | Keys of the fields that are visible right now. |
| `status` | `'idle' \| 'validating' \| 'submitting' \| 'success' \| 'error'` | |
| `result` | `SubmissionResponse \| null` | `{ id, status, success?, flags? }` after success. |
| `submitError` | `MirioError \| null` | The last submit failure. |
| `startedAt` | `string` | ISO time the form mounted (time-to-submit signal). |
| `sessionId` | `string \| null` | Partial-save session id; null until a multi-step form needs one. |
| `fields` | `Field[]` | All fields, flattened. |
| `currentPage` | `Page` | `schema.pages[pageIndex]`. |
| `isMultiStep` | `boolean` | More than one page in the schema. |
| `isFirstPage`, `isLastPage` | `boolean` | Relative to visible pages. |
| `turnstileToken` | `string \| null` | Set by `Turnstile`. |
| `success` | `SuccessBehavior \| undefined` | The schema's `settings.success` (the code the visitor runs); the server's echo only when the schema has none. |
| `successUrl` | `string \| null` | Resolved redirect/schedule URL after success (prefill + `utm_*`), for rendering a link instead of navigating. |
| `fieldId(key)` | `(key) => string` | The control id for a field. |
| `pageHeadingId(i)` | `(i) => string` | The heading id focus moves to on page change. |
| `isFieldVisible(key)`, `isPageVisible(i)` | `=> boolean` | Conditional logic results. |
| `setValue(key, value)` | | Sets a value and clears that field's error. |
| `setTouched(key)` | | Marks blurred; shows format errors for non-empty values. |
| `validatePage(i)` | `=> boolean` | Validates one page's visible fields, sets errors, focuses the first invalid control. |
| `nextPage()` | `=> Promise<boolean>` | Validates the current page, moves to the next visible page, fires a partial save. |
| `prevPage()` | | Moves to the previous visible page. |
| `goToPage(i)` | | Jumps to a page (clamped). |
| `submit()` | `=> Promise<void>` | Validates every visible field, jumps to the first failing page, otherwise posts. Ignored while submitting or after success. |
| `reset()` | | Back to initial values and page 0; rotates the session id. |
| `focusField(key)` | | Focuses a control by key (after render). |
| `setHoneypot(value)`, `setTurnstileToken(token)` | | Used by `Honeypot` and `Turnstile`. |
| `resolveSuccessUrl(success?, values?)` | `=> string \| null` | Same resolution as the automatic redirect, for any success/values. |
| `formProps` | `{ onSubmit, noValidate: true }` | Spread on your `<form>`. |

### `FormProvider` and `useForm()`
`<FormProvider form={form}>` makes the hook result available; `useForm()` returns it (throws outside a provider; `useOptionalForm()` returns `null` instead). The styled `Form` is a `FormProvider` too, so the hooks below work inside it.

### `useField(key)`
| Key | Type | Description |
| --- | --- | --- |
| `field` | `Field` | The schema field (throws if `key` is unknown). |
| `visible` | `boolean` | False when a `showWhen` hides it; render nothing. |
| `value`, `setValue(v)` | | |
| `onBlur()` | | Calls `setTouched`. |
| `error` | `string \| undefined` | |
| `touched` | `boolean` | |
| `id`, `labelId`, `descriptionId`, `errorId` | `string` | Ids to use on the control, label, help and error elements. |
| `inputProps` | `{ id, name, 'aria-invalid'?, 'aria-describedby'?, 'aria-required'?, onBlur }` | Spread on the control. `aria-required` instead of `required`, so Mirio's messages show, not the browser's. For a group (radios, rating), put `id`, `aria-labelledby={labelId}` and the `aria-*` props on the group element with `tabIndex={-1}`. |

### `usePage(index?)`
Returns `{ page, index, step, count, fields (visible), allFields, headingId, isVisible, isFirst, isLast, next, prev }` for the given or current page.

### `useFormStatus()`
Returns `{ status, isSubmitting, isSuccess, result, error }`.

### `Honeypot`
`<Honeypot name="_mirio_website" label="Website" />` renders a visually hidden text input (`data-mirio="honeypot"`, `aria-hidden`, `tabIndex={-1}`, `autoComplete="off"`, positioned off-screen with inline styles) whose value is sent as `meta.honeypot`. Both props are optional; `label` is the hidden label text. Needs no CSS. Put it inside your `<form>`.

### `Turnstile`
`<Turnstile siteKey="…" className? />` loads Cloudflare Turnstile once, renders the widget in `<div data-mirio="turnstile">` and feeds the token into the form. The styled `Form` renders it when `settings.turnstileSiteKey` or `createClient({ turnstileSiteKey })` is set. Mirio requires and checks the token only on forms whose schema sets the site key, once it has that widget's secret key (see [Turnstile](https://api.trymirio.com/docs/spam.md#turnstile)).

### Also exported
`prefillFromQuery(fields, search?)`, `evaluateCondition`, `visibleFieldKeys`, `visiblePageIndexes`, `pruneHiddenValues`, `resolveSuccessUrl`, `getOrCreateSessionId`, `clearSessionId`, `MirioError`, and the types `MirioFormState`, `UseMirioFormOptions`, `UseFieldResult`, `Condition`, `Actor`.

## Variants and states
- **Multi-step**: render `currentPage.fields` (or `usePage().fields`) and buttons calling `prevPage`/`nextPage`; make Next `type="submit"` so Enter advances. Show `stepIndex + 1` of `pageCount`.
- **Errors**: `errors[key]` per field; `submitError` for form-level failures (network, `rate_limited`, `agents_blocked`…). Server field errors arrive in `errors` too.
- **Success**: branch on `status === 'success'`; for redirect/schedule either let the hook navigate or pass `navigate` and use `successUrl`.

## Customization
Everything. The headless layer has no classes, no tokens and no `data-mirio` except on `Honeypot` and `Turnstile`. The styled components in `@trymirio/mirio` are a worked example of building on these hooks.

## Accessibility
The hooks give you the pieces; your markup decides. Minimums: spread `inputProps` on each control, put `id={labelId}` on the label and `htmlFor={id}` (or `aria-labelledby` on a group), give help and error elements the `descriptionId`/`errorId`, give page headings `id={headingId} tabIndex={-1}` so focus can land there, and keep the `Honeypot` inside the form.

## Related
[Form](https://api.trymirio.com/docs/components/form.md), [Field](https://api.trymirio.com/docs/components/field.md), [Conditional logic](https://api.trymirio.com/docs/conditional-logic.md), [Agents](https://api.trymirio.com/docs/agents.md), [API](https://api.trymirio.com/docs/api.md)

---

<!-- https://api.trymirio.com/docs/spam.md -->

# Spam and validation

The server decides. Every submission is validated against the registered schema version and scored for spam. Client validation is a convenience.

## Validation and normalization

Values are checked by type and constraint (see [Form schema](https://api.trymirio.com/docs/schema.md)) and normalized: text trimmed, emails lowercased, phone numbers converted to E.164, URLs given a scheme, dates to `YYYY-MM-DD`. Invalid submissions get `400 validation_failed` with a message per field; the components show those messages inline.

Partial submissions validate only the pages completed so far.

## Spam scoring

| Signal | Score | Reason code |
| --- | --- | --- |
| Honeypot field filled | 100 | `honeypot` |
| Submitted under 2 seconds after the form loaded | 60 | `too_fast` |
| Disposable email domain | 50 | `disposable_email` |
| Three or more links in a text field | 40 | `links` |
| [Turnstile](#turnstile) on and token missing or invalid | 70 | `turnstile` |

A score of 70 or more marks the submission `spam`. Spam is stored and shown in the spam tab with its reasons; it never fires notifications or webhooks. Spam still counts toward the monthly response limit (see [Usage](https://api.trymirio.com/docs/limits.md)). Mark anything as not spam in the dashboard. The client always gets a normal success response, so bots learn nothing.

Rate limits apply per IP, per form and per origin. Over the limit the API returns `429`.

## Turnstile

[Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/) is an optional check that a person, not a script, filled in the form. It uses your own widget, in your Cloudflare account (free):

1. In the Cloudflare dashboard, open **Turnstile** and add a widget. List every hostname the form runs on (`example.com`, and `localhost` if you want the widget while developing). Copy its **site key** and **secret key**.
2. Put the site key in the schema: `settings: { turnstileSiteKey: '0x4AAAAAAA…' }`. The `Form` renders the widget and sends its token with the submission.
3. Give Mirio the secret key:

```bash
npx mirio turnstile set <secret key>
```

The CLI reads the site key from your schema files (pass `--site-key` when forms use more than one), Mirio checks the secret key with Cloudflare and stores it encrypted, and it is never shown again. API: `PUT /v1/project/turnstile` with `{ "siteKey": "…", "secret": "…" }`.

From then on Mirio checks each submission's token with Cloudflare. A missing or invalid token adds 70 (`turnstile`), which on its own marks the submission spam.

- **Use the secret key of the same widget as the site key.** A secret key only accepts its own widget's tokens, and Cloudflare can't tell Mirio that two keys belong together, so a mismatched pair sends every response to spam.
- Until Mirio has the secret key for a form's site key, its tokens aren't checked: registering the form prints a warning, and `npx mirio turnstile` lists which forms are checked.
- If Cloudflare can't be reached, or stops accepting the secret key (you rotated or deleted it), submissions are scored as if Turnstile were off; nothing goes to spam for that. After rotating, run `mirio turnstile set` with the new secret key.
- A token works once. Partial saves of a multi-step form don't use it (the final submit does), and requests made with the site's secret key (your own server, `mirio test`) skip the check.
- AI agents that submit through the API can't solve Turnstile, so on a form with Turnstile their responses go to spam. Leave it off on forms you want agents to fill.
- On a live form, `turnstileSiteKey` changes apply with the next production build, like `agents`.
- `npx mirio turnstile remove` deletes the secret key; tokens aren't checked after that.

To try it, Cloudflare's [test keys](https://developers.cloudflare.com/turnstile/troubleshooting/testing/) work: site key `1x00000000000000000000AA` with secret key `1x0000000000000000000000000000000AA` always passes, `2x00000000000000000000AB` with `2x0000000000000000000000000000000AA` always fails. Switch to your widget's keys before going live.

## What is never dropped

- Spam goes to the spam view.
- A submission from a schema that was never registered is accepted, validated against the production version (or the latest when the form has no production registration yet), flagged `unregistered_schema`, and stored with any unknown keys under `extra`. The owners get at most one digest email per form per 24 hours, counting the flagged responses since the previous one, with the fix: `npx mirio env vercel` (or `netlify`, or `print`) so the site registers its forms on every build.
- Submissions from a localhost origin on a live (claimed) project are stored as `test`: you can try the site locally against the real project. Test responses are enriched and reviewed so you see how triage sorts them, but they are never delivered, never counted as responses, and are hidden in the dashboard unless "Show test responses" is on. Sandbox projects keep treating localhost as normal traffic.
- Forms are never cut off.

---

<!-- https://api.trymirio.com/docs/enrichment.md -->

# Enrichment

Every completed submission on a claimed site (and every test response, so you can see the result) is enriched before it is delivered, so the dashboard, emails, Slack messages, webhooks and database rows all carry the same signals.

```json
"enrichments": {
  "email": { "address": "ada@acme.com", "domain": "acme.com", "isFreeMail": false, "isRole": false, "isDisposable": false, "mxValid": true },
  "duplicate": { "count": 1, "firstSeenAt": "2026-09-30T10:12:00Z" },
  "velocity": { "ipSubmissions1h": 1 },
  "company": { "domain": "acme.com", "name": null, "website": "https://acme.com" }
}
```

## Signals

| Signal | Meaning |
| --- | --- |
| `email.isFreeMail` | Gmail, Outlook, iCloud and similar consumer domains |
| `email.isRole` | `info@`, `sales@`, `support@` and similar shared addresses |
| `email.isDisposable` | Throwaway domains |
| `email.mxValid` | The domain accepts mail (`null` when the lookup timed out) |
| `duplicate` | The same email submitted this form before |
| `velocity` | Submissions from the same IP across the project in the last hour |
| `company` | Derived from a work-email domain; the name is filled when a company data provider is configured (follow-up) |

The dashboard shows these in plain words under a response's What Mirio found ("Work address at acme.com", "Responded once on this form"), with the raw values under Technical details. There is no score: for a judgement of how well a response matches what you are looking for, use [triage](https://api.trymirio.com/docs/ai-review.md), whose fit level is based on your own description. The signals are also part of what triage is told.

## What enrichment never does

- It never blocks or drops a submission. Signals are context, not a verdict.
- It never changes the visitor's values. Enrichment lives in its own `enrichments` object.
- It never runs on partials, spam or sandbox projects.

---

<!-- https://api.trymirio.com/docs/ai-review.md -->

# Triage (AI review)

On claimed sites, Mirio reads every completed response once and writes down what a person on your team would want to know before opening it:

- **summary**: up to three sentences (320 characters): who this is, what they want, and anything in Mirio's signals that changes how to read it, like a repeat sender, a personal address on a business request or the campaign they came from
- **category**: one of your form's categories (Sales lead, Support, Partnership, Job seeker, Vendor pitch, Other by default)
- **fit**: `high`, `medium` or `low` against your description of a great response, with a one-clause reason
- **facts**: company, role, team size, budget, timeline and urgency, only when the person stated them
- **spam**: a second opinion, for pitches and junk that the rule-based checks let through

```json
"review": {
  "summary": "Head of research at a 220-person health company wants weekly interview tooling, starting this month. Came from your spring Google campaign.",
  "category": "Sales lead",
  "fit": "high",
  "fitReason": "Runs research weekly at a 220-person company and wants to start this month.",
  "facts": { "company": "Lumen Health", "role": "Head of research", "teamSize": "220", "timeline": "This month" },
  "spam": { "likely": false, "reason": null },
  "model": "gpt-6-luna",
  "reviewedAt": "2026-10-15T09:12:03Z"
}
```

The review is part of every submission record (read API, CSV columns `ai_summary`, `ai_category`, `ai_fit` and `ai_group_<key>` per group, webhook payloads, and the Postgres destination's `mirio_review`, `mirio_ai_category`, `mirio_ai_fit` and `mirio_ai_<key>` columns). Email and Slack notifications lead with the summary, then the fit, the category and each group's pick on one line ("High fit · Sales lead"), and why it fits on the line under it.

## Turn it on

It is on by default for every form. Its settings live in Mirio, not in the schema file: set them in the dashboard (the form's **Setup → Triage**) or from the CLI:

```bash
npx mirio review demo-request --ideal "Research or product teams at companies with 50+ people who run customer research at least monthly and want to start this quarter."
npx mirio review demo-request --summary "Lead with what they want to buy and when. Mention their budget if they gave one."   # optional
npx mirio review demo-request --categories "Sales lead,Support,Partnership,Job seeker,Vendor pitch,Other"   # optional, 2 to 12
npx mirio review demo-request --off      # turn it off for this form (--on to turn it back on)
npx mirio review demo-request            # show the current settings
```

The API is `GET` / `PUT /v1/project/forms/:slug/review`: `PUT` sends the full settings `{ idealResponse?, summary?, categories?, enabled? }` and replaces what is there (responses come back as `{ review, effective }`). Without an ideal response, responses still get a summary, a category and facts, but no fit. `summary` (3 to 500 characters) tells triage what each summary should focus on, leave out or be written in; without it the summary says who the person is and what they want. Schemas that still declare `settings.review` keep working for one release: the first push imports it when Mirio has nothing set for the form, then prints a note to remove it from the file.

## Writing a good `idealResponse`

The fit level is only as good as this sentence. Describe the response you would drop everything for, in terms the person could actually write in your form:

- **Name observable things.** "50+ people", "runs research monthly", "wants to start this quarter" can be checked against answers. "A great customer" cannot.
- **Match your questions.** If you care about team size, ask for it. Mirio judges fit only from what the person wrote; it never looks people up.
- **One or two sentences.** List the two or three things that matter most; leave out nice-to-haves.
- **Say what is not a fit** when it is common: "Agencies and students are not a fit."

Good: `B2B SaaS teams of 20 to 500 people replacing a spreadsheet-based onboarding process within the next two months.`
Too vague: `Serious companies that would get value from our product.`

## More groups

Besides the category and fit, you can have triage sort responses into up to five groups of your own, like **Urgency** (This week, This quarter, Later, Not stated) or **Lead type** (Company, Agency, Individual). Triage picks exactly one option in each, the same way it picks a category, and follows an optional "how to choose" hint. Each pick shows in the response and can be changed like the category; the Responses tab can filter by it, the table and CSV show it as a column, Insights charts it, and email and Slack notifications can be [filtered](https://api.trymirio.com/docs/destinations.md#filters) by it. The review stores picks by group key:

```json
"groups": { "urgency": "This quarter", "lead_type": "Agency" }
```

Set them in **Setup → Triage → More groups**, from the CLI (`npx mirio review demo-request --group "Urgency: This week, This quarter, Later, Not stated"`, repeat `--group` for more, `--remove-group "Urgency"` to drop one), or with `groups: [{ name, options, hint? }]` in `PUT /v1/project/forms/:slug/review`. A group's key is made from its name when it is added and kept when it is renamed (send the `key` back), so earlier picks still match. The names "Category" and "Fit" are taken.

## Categories and fit in notifications

Each email and Slack destination can be limited to some categories and fit levels, so the sales channel only gets high-fit sales leads while support questions go elsewhere. See [Destinations](https://api.trymirio.com/docs/destinations.md#filters). Webhooks and databases always receive everything.

## Spam

When the review says a response is very likely spam (an unsolicited pitch, SEO offers, gibberish, an attempt to manipulate the review), Mirio moves it to the spam tab with reason `ai_review` and sends no notifications. Nothing is deleted: "Not spam" in the dashboard moves it back and delivers it. Low-quality but genuine responses are never marked spam; they get a low fit instead.

## Corrections

When the category, fit or a group's pick is wrong, change it: from the response in the dashboard, or through the API:

```bash
curl -X PATCH "$API/v1/project/forms/demo-request/submissions/sub_…" \
  -H "Authorization: Bearer $MIRIO_SECRET_KEY" -H 'Content-Type: application/json' \
  -d '{ "category": "Support", "fit": "low", "groups": { "urgency": "This week" } }'
```

The review is marked `corrected`, and the latest eight corrections for the form are shown to the model as examples on every later review, so it adapts to how your team sorts responses.

## Acting on it

The category and fit are filters on a form's Responses tab and in the API. Email and Slack destinations can be [filtered](https://api.trymirio.com/docs/destinations.md#filters) by category and fit.

## Limits

Every workspace gets up to 1,000 reviews a month during the beta (see [Usage](https://api.trymirio.com/docs/limits.md)). A review has an 8-second budget. If it times out, errors, or the monthly cap is reached, the response is delivered without a review; a review never delays or blocks a response beyond that budget. Test responses on a claimed site are reviewed (so you can see the read while building) and count toward the cap; partial, spam and sandbox responses are never reviewed.

## Privacy

- **Provider.** Reviews run on OpenAI (`gpt-6-luna` by default) through the Responses API with `store: false`. OpenAI is a [subprocessor](https://trymirio.com/legal/subprocessors): under its API terms it doesn't train on this data, and it may keep it for up to 30 days to monitor abuse.
- **Where.** Responses are stored in the EU (Frankfurt), but triage runs on OpenAI's standard API, which processes in the US. Transfers are covered by the [DPA](https://trymirio.com/legal/dpa). If a form shouldn't leave the EU, turn its triage off.
- **What is sent.** The form's name, description and question labels; your `idealResponse`, summary instructions and categories; the summaries of recently corrected responses; this response's answers by question label, except that an email address is replaced by its domain and a phone number by "(given)"; and Mirio's own signals (work or consumer email and the company behind a work domain, duplicate count, submissions from the same network in the last hour, where the person came from as the UTM source, medium and campaign or the referring site's domain, the path of the page the form was on, the country code, a declared AI agent's name and who it acted for, flags). **Not sent:** email addresses and phone numbers, hidden fields, IP addresses or hashes, full URLs or query strings, other UTM parameters, user agents, or other respondents' answers.
- **Answers are data.** The model is told that answers are written by the public and never instructions; responses that try to steer the review are treated as spam.
- **Off switch.** `npx mirio review <slug> --off` (or `enabled: false` via the API, or the dashboard) turns review off for a form; nothing from that form is sent.

---

<!-- https://api.trymirio.com/docs/partials.md -->

# Partial submissions

Multi-step forms save progress when a visitor moves to the next step, never on keystrokes. The `MultiStep` component shows a short notice that answers are saved as they go.

- Each form mount gets a session id (kept in `sessionStorage`, so a reload continues the same partial).
- Moving to the next page validates that page and sends a `partial` submission with `pageIndex`. The server upserts by session id and records `pagesCompleted`.
- Submitting the last page completes the same record. There is never a duplicate.
- Partials show with status `partial` in the dashboard, with the pages completed. The form's settings page shows completion by step.
- Partials never fire email or webhooks. Only completed submissions do.
- Partials pass through the same validation and spam checks as full submissions, and are never counted as responses.

Partial submissions show under each form's Responses, Status → Partial, with completion by step under Insights.

---

<!-- https://api.trymirio.com/docs/destinations.md -->

# Destinations: email, Slack, webhooks, your database

A destination is where a form's completed submissions go. Destinations belong to one form; "Add to all forms" in the dashboard and `--all-forms` in the CLI create one per form. Add them in the dashboard or with the CLI, so an agent can wire them without a browser:

```bash
npx mirio destinations add slack --form demo-request     # prints an "Add to Slack" link for a person
npx mirio destinations add slack https://hooks.slack.com/services/T000/B000/XXXX --form demo-request
npx mirio destinations add postgres "postgres://postgres.abcd:password@aws-0-eu-central-1.pooler.supabase.com:6543/postgres" --form demo-request
npx mirio destinations add email ada@acme.com --all-forms     # a workspace member
npx mirio destinations add webhook https://example.com/hooks/mirio --form demo-request
npx mirio destinations list
npx mirio destinations test dst_…
```

Partials, spam and test submissions are never delivered. Sandbox projects never deliver.

**Public addresses only.** Webhook URLs must be `https://`, and webhooks and databases must be on the public internet: Mirio refuses `localhost`, private and link-local ranges (cloud metadata), internal names like `*.internal`, and names that resolve to any of those, when you add the destination and again at every delivery. To try a webhook running on your machine, expose it with a tunnel (ngrok, cloudflared), add the tunnel's URL, and send it a sample with `mirio destinations test dst_…`. Test submissions (`mirio test`, or a live site's form on localhost) are never delivered.

**Email goes to workspace members only.** The person who claims a site (or creates it in the dashboard) gets email notifications on every form automatically, including forms added later; invite teammates to the workspace to add them. Outside addresses are refused (use Slack for shared inboxes and aliases).

## Filters

Email and Slack destinations can be limited to some [triage](https://api.trymirio.com/docs/ai-review.md) categories, fit levels and picks in the form's [groups](https://api.trymirio.com/docs/ai-review.md#more-groups), so `#sales` only hears about high-fit leads while support questions go to the support inbox:

```bash
curl -X POST "$API/v1/project/destinations" -H "Authorization: Bearer $MIRIO_SECRET_KEY" -H 'Content-Type: application/json' \
  -d '{ "type": "slack", "formSlug": "demo-request", "url": "https://hooks.slack.com/services/…", "filter": { "categories": ["Sales lead"], "fit": ["high", "medium"] } }'
```

- `categories`: the form's review categories (strings, up to 40 characters). `fit`: any of `high`, `medium`, `low`. `groups`: options per group key, e.g. `{ "urgency": ["This week"] }`. All optional; a response must match every list that is set. A group the response has no pick in (an older review) doesn't filter.
- CLI: `--categories "Sales lead" --fit high --group "Urgency: This week, This quarter"` (repeat `--group`; the key comes from the group's name).
- No filter, or empty lists, means every response.
- Filters fail open: when a response has no review (the form has review off, the review failed or timed out, or the monthly review limit was reached), it is delivered.
- Webhooks and databases cannot be filtered; they receive every completed response so your own systems stay complete. Filter on `review.category`, `review.fit` and `review.groups` there.
- In the dashboard, each email and Slack destination has a "Send: All responses ▾" menu for the same setting.

## Slack

**Add to Slack** (the easy way): in the form's Delivery settings, "Add Slack channel" → **Add to Slack**. Slack asks which channel (private channels too), and the channel shows up by name. Mirio's Slack app only gets permission to post to the channel you pick; it can't read messages or see other channels.

**From the CLI**, leave out the URL. An agent can't click through Slack, so the CLI prints a link for a person in the site's workspace and waits until they've picked the channel:

```bash
npx mirio destinations add slack --form demo-request      # or --all-forms; --no-wait to print the link and exit
```

The link works for 30 minutes and only for members of the site's workspace (it signs them in first). `--json` prints `{ connectUrl, expiresAt }` without waiting; `mirio destinations list` shows the channel once it's connected. API: `POST /v1/project/destinations/slack-link` with `{ "formSlug": "…" }` or `{ "allForms": true }`.

**An incoming webhook URL** still works (Slack: create an app → Incoming Webhooks → add one for the channel), for workspaces that don't allow installing apps.

Each completed submission posts a message with the form name, Mirio's summary, then the fit, category and each group's pick with why it fits on the line under them (when triage is on), up to 10 fields ("+N more fields" when there are more; long answers are shortened to 200 characters), flags such as `agent`, the page URL, where the person came from ("From /pricing · via google / cpc · landed on /blog/launch"; see [attribution](https://api.trymirio.com/docs/attribution.md)), and a button to the submission in Mirio.

## Your database (Postgres, Supabase)

Mirio writes each completed submission into a table in your own Postgres database. Nothing to build: give it a connection string and it keeps the table in sync with your schema.

- The table is created on first delivery, default name `mirio_<slug>`, schema `public`.
- One column per field, named after the field key, typed by field type (`text`, `double precision`, `integer`, `boolean`, `date`, `text[]`). New fields in a new schema version add columns automatically; removed fields keep their column.
- System columns: `mirio_id` (primary key), `mirio_form`, `mirio_status`, `mirio_flags`, `mirio_enrichments`, `mirio_review` (the AI review as JSON), `mirio_ai_category`, `mirio_ai_fit`, one `mirio_ai_<group key>` text column per triage group (added when a group is), `mirio_meta`, `mirio_values` (the full values as JSON), `mirio_submitted_at`, `mirio_received_at`.
- Writes are upserts on `mirio_id`, so retries and replays never duplicate rows.
- The connection string is encrypted at rest and never shown again.
- The host must be public (see above). If Mirio can't connect, the error says so without detail about the network (a wrong password or a missing database is reported as such).

**Supabase:** Project settings → Database → Connection string → Transaction pooler (port 6543), URI format. Use a dedicated database role with `CREATE` on the schema if you prefer not to use `postgres`. Row Level Security does not apply to this role's inserts, so read the table through your normal policies.


## Webhooks

Signed `POST`s with retries for 24 hours and replay from the dashboard. See [Webhooks and email](https://api.trymirio.com/docs/webhooks.md). Use a webhook when you want to run your own logic (create a CRM lead, start a sequence) rather than store rows.

## A recipe: Supabase from a webhook instead

If you would rather own the insert, a Next.js route handler is about twenty lines:

```ts
// app/api/mirio/route.ts
import { createClient } from '@supabase/supabase-js';
import { createHmac, timingSafeEqual } from 'node:crypto';

export async function POST(req: Request) {
  const raw = await req.text();
  const header = req.headers.get('mirio-signature') ?? '';
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]));
  const expected = createHmac('sha256', process.env.MIRIO_WEBHOOK_SECRET!).update(`${t}.${raw}`).digest('hex');
  if (!v1 || expected.length !== v1.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) return new Response('bad signature', { status: 401 });

  const event = JSON.parse(raw);
  const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE_KEY!);
  const { error } = await supabase.from('demo_requests').upsert({ id: event.data.id, ...event.data.values, category: event.data.review?.category, received_at: event.createdAt });
  return error ? new Response(error.message, { status: 500 }) : new Response('ok');
}
```

Return a 2xx only after the insert succeeds; Mirio retries anything else.

---

<!-- https://api.trymirio.com/docs/webhooks.md -->

# Webhooks and email

Completed submissions are delivered to every enabled destination on their form: email, Slack, webhooks and databases. Partials, spam and test submissions never trigger deliveries. Sandbox projects never deliver.

## Email

Email notifications go to workspace members: the person who claims the site gets them on every form, and you add teammates per form in the dashboard (Setup → Delivery) or with `npx mirio destinations add email <member> --form <slug>` (`--all-forms` for every form). There is no verification step and no outside addresses; use Slack for shared inboxes and aliases. One email per completed submission: Mirio's one-line summary and category first (when triage is on), then each field, and a link to the response.

## Webhooks

Add a URL in the form's Setup → Delivery in the dashboard, or `npx mirio destinations add webhook <url> --form <slug>`. You get a signing secret once; store it as an environment variable.

Request: `POST` with `Content-Type: application/json`, `User-Agent: Mirio-Webhooks/1`, `Mirio-Delivery-Id`, `Mirio-Signature`.

```json
{
  "id": "dlv_…",
  "type": "submission.completed",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "data": { "id": "sub_…", "status": "complete", "values": { "email": "a@b.co" }, "form": { "id": "frm_…", "slug": "waitlist", "name": "Waitlist" }, "meta": { … }, "versionNumber": 3, … }
}
```

### Verify the signature

`Mirio-Signature: t=1760356800,v1=<hex>` where `v1 = HMAC-SHA256(secret, "<t>.<raw body>")`.

```ts
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyMirioSignature(rawBody: string, header: string, secret: string, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1?.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
```

Respond with any 2xx within 10 seconds. Anything else is retried.

### Retries and replay

Backoff: 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours, then every 6 hours until 24 hours after the first attempt. The delivery log in the dashboard shows every attempt with the response code. Replay any delivery with one click; a replay is a fresh delivery with the same payload.

---

<!-- https://api.trymirio.com/docs/agents.md -->

# Agent-native forms

Forms built with Mirio can be filled in by AI agents as a first-class, declared channel. You decide per form what happens.

## The policy

```ts
settings: {
  agents: 'accept',    // 'accept' (default) | 'block'
  agentNotes: 'Demo requests for Versive. Answer on behalf of the person you work for; use their work email.',
}
```

| Policy | What happens to a submission declared by an agent |
| --- | --- |
| `accept` (default) | Stored and delivered like any other, always labeled with the flag `agent`. The dashboard shows an Agent badge and a filter. |
| `block` | Rejected with `403 agents_blocked`. The hint tells the agent to hand the form to the human. |

Older schema files that say `'allow'` or `'flag'` keep working: both mean `accept`. On a live form, the policy is enforced by the server, so a change takes effect with the next production build (development and preview pushes keep production's policy).

Declared agents skip the "submitted too fast" spam signal, because an honest agent is not a bot in the abusive sense. Honeypot, disposable-email and rate limits still apply, and so does [Turnstile](https://api.trymirio.com/docs/spam.md#turnstile): an agent can't solve it, so on a form with Turnstile on, agent responses go to spam.

Mirio does not guess: responses that do not declare an agent are not labeled, whatever their user agent or typing speed. Declared agent responses carry the `agent` flag, so you can filter them on the Responses tab or route them from a [webhook](https://api.trymirio.com/docs/destinations.md).

## How an agent submits

Every form describes itself at a public URL:

```
GET https://api.trymirio.com/v1/projects/<projectId>/forms/<slug>/schema.json
```

The response lists the pages and fields (with constraints, options and conditions), the agent policy and notes, and a ready-to-send example request under `submit`. An agent then POSTs to the submission endpoint with `meta.actor`:

```json
{
  "schemaHash": "<from schema.json>",
  "values": { "email": "ada@acme.com", "name": "Ada Lovelace", "interest": ["surveys"] },
  "meta": { "actor": { "type": "agent", "name": "Claude", "onBehalfOf": "Ada Lovelace" }, "pageUrl": "https://acme.com/demo" }
}
```

The same origin rules apply as for browsers: a sandbox project accepts localhost only, and a live project accepts the site's domains (`mirio domains`). Server-side agents that have no browser origin should send the request through the site's own backend, or the site owner can allow the agent's origin.

The React components do this automatically when you pass an actor to the client:

```ts
export const mirio = createClient({ projectId: '…', actor: { type: 'agent', name: 'my-signup-bot' } });
```

## Reading what agents sent

- Dashboard: the submissions table has a Source filter (humans, agents) and shows the actor name in the detail panel.
- Webhooks and the read API: `flags` includes `agent`, and `meta.actor` carries the declaration.
- Slack messages show the flags in the context line.

---

<!-- https://api.trymirio.com/docs/api.md -->

# HTTP API

Base URL: `https://api.trymirio.com` (or your `apiUrl`). JSON in and out. Errors always have this shape:

```json
{ "error": { "code": "validation_failed", "message": "2 fields are invalid", "fields": { "email": "Enter a valid email address" }, "hint": "…", "docs": "https://api.trymirio.com/docs/schema.md" } }
```

Codes: `project_not_found`, `form_not_found`, `project_unclaimed` (403), `origin_not_allowed` (403), `agents_blocked` (403), `validation_failed` (400), `schema_rejected` (400), `rate_limited` (429, with `Retry-After`), `unauthorized` (401), `forbidden` (403), `not_found` (404), `conflict` (409), `invalid_request` (400), `internal` (500).

## Submissions (public, used by the SDK)

`POST /v1/projects/{projectId}/forms/{slug}/submissions`

CORS is limited to the site's domains (`mirio domains`; sandbox projects: localhost only). Requests without an `Origin` header are rejected unless they carry the project secret key. Headers: `Idempotency-Key` (optional, recommended), `X-Mirio-Test: 1` (with the secret key; stores a `test` submission). A localhost `Origin` on a live project is also stored as `test` (enriched, never delivered or counted).

```json
{
  "schemaHash": "sha256 hex of the canonical schema (the SDK computes it)",
  "values": { "email": "a@b.co", "name": "Ada" },
  "status": "complete",
  "sessionId": "uuid, required for partial",
  "pageIndex": 0,
  "meta": { "pageUrl": "…", "referrer": "/pricing", "landingPage": "/blog/x", "entryReferrer": "https://…", "utm": { "source": "x" }, "startedAt": "ISO", "honeypot": "", "turnstileToken": "…",
            "actor": { "type": "agent", "name": "Claude", "onBehalfOf": "Ada" } }
}
```

Response `200`: `{ "id": "sub_…", "status": "complete" | "partial" | "test", "success": { …settings.success }, "flags": ["unregistered_schema", "agent"] }`. Spam is stored but never revealed to the client; the response says `complete`. A declared agent (`meta.actor.type: "agent"`) always gets the `agent` flag, or `403 agents_blocked` when the form's policy is `block`.

## Project API (secret key)

`Authorization: Bearer sk_…`. This is what the CLI uses.

| Method and path | Purpose |
| --- | --- |
| `POST /v1/projects` | Create a sandbox project (no auth; rate limited). Returns the secret key once and the claim link. |
| `POST /v1/projects/link` | Connect a repo to a site created in the dashboard (no auth; same rate limit as provisioning): `{ "code": "mil_XXXXX-XXXXX-XXXXX-XXXXX" }` → `{ project, secretKey, drafts: [{ slug, name, template, brief }] }`. Codes are single use and last 24 hours (`400` when used or expired: copy a fresh prompt). A site that already has a key gets `409 conflict` unless the code is a reconnect code, which replaces the key (the old repo stops working). `mirio init --link <code>` calls this. |
| `GET /v1/project` | Status: mode, claim link, origins, workspace, forms with 7-day counts. Drafts are listed with `status: "draft"` and null version fields. |
| `PUT /v1/project/forms/{slug}` | Register a schema: `{ "schema": …, "source"?: { "env": "production" \| "preview" \| "development" \| "unknown", "branch"?, "commit"?, "url"? } }`. The framework plugin and `mirio sync` fill `source` from the host; without it the push is `unknown` and never changes production. A production push makes this version the form's questions (`productionVersionNumber`) and marks the form live; preview and development pushes register versions without changing production or, once the form is live, its settings. Returns the version, whether it was created, the diff and warnings (type changes on kept fields, removed fields that have answers). |
| `GET /v1/project/forms` | List forms, each with `status`: `draft` (created in the dashboard, waiting for its schema file), `active` or `archived`. Pushing a draft's slug registers its first version and makes it `active`, keeping its notifications and triage settings. Drafts take no responses and have no `schema.json` (`404 form_not_found`). |
| `GET /v1/project/forms/{slug}` | Form (`versionNumber` = latest registration, `productionVersionNumber`, `liveAt`), settings, and versions with fields and provenance (`env`, `branch`, `commit`, `deployUrl`, `productionAt`). |
| `GET /v1/project/forms/{slug}/submissions?status=&q=&limit=&cursor=` | Paged submissions, newest first. `status` is what a response is: `all` (default), `complete`, `partial`, `spam`, `test`. `q` searches the answers. |
| `GET /v1/project/forms/{slug}/submissions/{id}` | One submission. |
| `PATCH /v1/project/forms/{slug}/submissions/{id}` | `{ "category": "<review category>", "fit": "high" \| "medium" \| "low", "groups": { "<group key>": "<option>" } }` (any of them). They correct triage (see [AI review](https://api.trymirio.com/docs/ai-review.md#corrections)). Every change is recorded in the response's history. Other fields are read only. Returns the updated record. |
| `GET /v1/project/forms/{slug}/export.csv?status=&q=` | CSV: `id`, `status`, `ai_summary`, `ai_category`, `ai_fit`, `ai_group_<key>` per triage group, `created_at`, one column per field across versions, `page_url`, `referrer`, `landing_page`, `entry_referrer`, `utm_*`, `flags`. `status` defaults to `complete`. |
| `GET` / `PUT /v1/project/forms/{slug}/review` | Triage settings: `{ "review": { "enabled"?, "idealResponse"?, "summary"?, "categories"?, "groups"? }, "effective": { … } }`. `groups` is up to 5 `{ key?, name, options, hint? }`: triage picks one option in each. `summary` is what each summary should focus on, in plain words. `PUT` replaces them with the body you send. |
| `GET` / `POST` / `DELETE /v1/project/domains` | The site's domains: `{ "domains": ["https://acme.com", "https://*.acme.com"] }`. `POST { "domain": "acme.com" }` adds one (normalized); `DELETE ?domain=acme.com` removes one. |
| `GET` / `PUT` / `DELETE /v1/project/turnstile` | The site's Cloudflare Turnstile widget: `{ "siteKey": "0x4AAAAAAA…" \| null, "forms": [{ "slug": "contact", "siteKey": "0x4AAAAAAA…", "verified": true }], "note"?: "…" }`. `PUT { "siteKey", "secret" }` stores the secret key encrypted after Cloudflare accepts it (it is never returned); `DELETE` removes it. See [Turnstile](https://api.trymirio.com/docs/spam.md#turnstile). |
| `GET /v1/project/destinations` | List destinations (never includes secrets; a channel connected with "Add to Slack" shows as `#channel (Workspace)`). |
| `POST /v1/project/destinations` | `{ type: 'email' \| 'webhook' \| 'slack' \| 'postgres', formSlug \| allForms: true, email?, url?, connectionString?, table?, schema?, label?, filter?: { categories?, fit?, groups?: { <group key>: [options] } } }`. Destinations are per form; `allForms` creates one per form and returns `{ destinations }`, `formSlug` returns `{ destination }`. Email goes to workspace members only. `filter` is for email and Slack only. Webhooks return the signing secret once. |
| `POST /v1/project/destinations/slack-link` | `{ formSlug } \| { allForms: true }` → `201 { url, expiresAt, formSlug }`: a 30-minute link to the dashboard's "Add to Slack" for a person in the site's workspace (claimed sites only). Webhook and database URLs must be public https; see [destinations](https://api.trymirio.com/docs/destinations.md). |
| `DELETE /v1/project/destinations/{id}` | Remove a destination. |
| `POST /v1/project/destinations/{id}/test` | Send a sample submission to it. |

Public, no auth: `GET /v1/projects/{projectId}/forms/{slug}/schema.json` describes a form for agents (fields, conditions, agent policy, an example request). See [Agent-native forms](https://api.trymirio.com/docs/agents.md).

Submission record:

```json
{
  "id": "sub_…", "formId": "frm_…", "schemaVersionId": "sv_…", "versionNumber": 3,
  "status": "complete", "values": { "email": "a@b.co" }, "extra": {},
  "sessionId": null, "pagesCompleted": null, "flags": [], "spamScore": 0, "spamReasons": [],
  "meta": { "pageUrl": "…", "referrer": "/pricing", "landingPage": "/blog/x", "entryReferrer": "https://news.ycombinator.com", "utm": {}, "userAgent": "…", "country": "DE" },
  "enrichments": { "email": { "domain": "b.co", "isFreeMail": false, "isRole": false, "isDisposable": false, "mxValid": true }, "duplicate": null, "velocity": { "ipSubmissions1h": 0 } },
  "review": { "summary": "…", "category": "Sales lead", "fit": "high", "fitReason": "…", "facts": { "company": "…" }, "spam": { "likely": false, "reason": null }, "model": "gpt-6-luna", "reviewedAt": "…" },
  "createdAt": "…", "completedAt": "…"
}
```

`status` is what a response is (Mirio sets it). `review` is [triage](https://api.trymirio.com/docs/ai-review.md), `null` when review is off, pending or failed.

## Read API (workspace API key)

`Authorization: Bearer mi_…`, created in the dashboard. Read only.

| Method and path | Purpose |
| --- | --- |
| `GET /v1/forms` | All forms in the workspace. |
| `GET /v1/forms/{formId}/submissions` | Same query parameters and shape as above. |
| `GET /v1/forms/{formId}/submissions/{id}` | One submission. |
| `GET /v1/forms/{formId}/export.csv` | CSV, same columns and filters as above. |

## Rate limits

Per IP 60 submissions a minute, per form and per origin 600 a minute, provisioning 5 an hour per IP. Over the limit returns `429` with `Retry-After`. The SDK retries 5xx and network errors, never 4xx.

---

<!-- https://api.trymirio.com/docs/limits.md -->

# Usage

Mirio is free during the beta, and every workspace is on the Beta plan: unlimited forms, sites and members, partial submissions, triage, every destination (email, Slack, webhooks, your database), the full history and the read API. Paid plans, and a free plan, come after the beta (see [After the beta](#after-the-beta)).

What is counted, and shown under **Settings → Usage** in the dashboard:

| | Counted | Beta plan |
| --- | --- | --- |
| Responses | Completed responses this month, spam included (partial and test responses are not counted) | 1,000 a month per workspace |
| Triage | Reviews this month, including test responses | 1,000 a month per workspace |

When the triage limit is reached, responses keep arriving and are delivered as usual, just without triage until the next month. If a workspace needs more than the beta's limits, [get in touch](https://trymirio.com/contact).

Other limits:

- Submissions: 60 a minute per IP, 600 a minute per form and per origin (`429` with `Retry-After`).
- Creating sandbox projects: 5 an hour per IP.
- Sandbox (unclaimed) data is deleted after 72 hours. Claimed sites keep everything.
- A submission body is at most 256 KB.

## After the beta

- Mirio moves to paid plans and keeps a free plan.
- Workspaces from the beta get a discount.
- You're never charged unless you choose a paid plan.

---

<!-- https://api.trymirio.com/docs/changelog.md -->

# Changelog

What changed in each `@trymirio/mirio` release, newest first (up to 0.1.6 the package was `kibbleforms`, and its notes keep the old names). Check this when you upgrade: anything that changes how a form looks or registers is called out. Install the latest with `npm install @trymirio/mirio@latest`; `npx mirio --version` prints the one you have.

## 0.2.0 (2026-11-04)

**Kibble is now Mirio.** The package is `@trymirio/mirio` (it was `kibbleforms`), the CLI is `mirio`, and the site, docs and API moved to trymirio.com. Forms look the same, but nothing reads the old names, so a site set up with `kibbleforms` renames them once:

| Before | Now |
| --- | --- |
| `kibbleforms` and its subpaths (`kibbleforms/next`, `/vite`, `/headless`, `/client`, `/schema`, `/styles.css`, `/theme.css`, `/themes/*.css`) | `@trymirio/mirio`, `@trymirio/mirio/next` and so on |
| `npx kibbleforms init`, `npx kibble <command>` | `npx @trymirio/mirio init`, `npx mirio <command>` |
| `kibble.json`, `.kibble/secret` | `mirio.json`, `.mirio/secret` (and `.mirio/` in `.gitignore`) |
| `KIBBLE_SECRET_KEY`, `KIBBLE_API_URL`, `KIBBLE_ENV`, `KIBBLE_PRODUCTION_BRANCH`, `KIBBLE_NO_UPDATE_CHECK` | `MIRIO_SECRET_KEY`, `MIRIO_API_URL`, `MIRIO_ENV`, `MIRIO_PRODUCTION_BRANCH`, `MIRIO_NO_UPDATE_CHECK` |
| `KibbleProvider`, `useKibbleForm`, `KibbleAttribution`, `KibbleError`, `withKibble` (Next.js), `kibble()` (Vite) and the other `Kibble…` names | `MirioProvider`, `useMirioForm`, `MirioAttribution`, `MirioError`, `withMirio`, `mirio()`, `Mirio…` |
| CSS variables `--kb-*`; utilities `bg-kb-*`, `text-kb-*`, `rounded-kb` and the rest; the `kb-check` class | `--mirio-*`; `bg-mirio-*`, `text-mirio-*`, `rounded-mirio`; `mirio-check` |
| `data-kibble` on the form's root, `data-kb="…"` on its parts, `data-kb-size`, `data-kb-color-scheme` | `data-mirio-root`, `data-mirio="…"`, `data-mirio-size`, `data-mirio-color-scheme` |
| `api.kibbleforms.com` | `api.trymirio.com` |
| `X-Kibble-Test` | `X-Mirio-Test` |

The forms folder stays wherever `formsDir` in the config points. `mirio init` writes its AGENTS.md section between new markers (`<!-- mirio:start -->`), so delete the old Kibble section once it has.

**Changed for every site, whatever version it runs:**

- Webhooks are signed in `Mirio-Signature` (it was `Kibble-Signature`), with `Mirio-Delivery-Id` and the user agent `Mirio-Webhooks/1`. Update the header your receiver checks.
- The Postgres destination writes `mirio_*` columns (`mirio_id`, `mirio_status`…; they were `kibble_*`), and new tables are named `mirio_<form>`. Rename the columns of an existing table, or drop it and let Mirio create it again.
- Workspace API keys start with `mi_` and dashboard link codes with `mil_`. Keys that start with `kb_` no longer work: create a new one under Settings → API keys.

## 0.1.6 (2026-11-03)

**Turnstile checks tokens now:**

- `kibble turnstile set <secret key>` gives Kibble your Turnstile widget's secret key. It reads the site key from `settings.turnstileSiteKey` in your schema files (`--site-key` when forms use more than one), Kibble checks the secret key with Cloudflare and stores it encrypted, and it's never printed back. `kibble turnstile` lists which forms are checked; `kibble turnstile remove` deletes the key. See [Turnstile](https://api.trymirio.com/docs/spam.md#turnstile).
- Before, Kibble rendered the widget but checked no tokens. If a form already sets `turnstileSiteKey`, registering it now warns until you run `kibble turnstile set`; from then on, responses with a missing or invalid token go to spam. Nothing changes in how forms look.

**Setup:**

- The AGENTS.md section `kibble init` writes now connects Slack with "Add to Slack" (`npx kibble destinations add slack --form <slug>` prints a link for a person), like the docs, instead of asking for a webhook URL.

## 0.1.5 (2026-10-27)

**How forms look** (styled components; restyle with `classNames` if you prefer the old spacing):

- Single and multiple choice options sit closer together: 4px apart instead of 8px.
- The "Optional" mark next to a label is lighter (70% of the muted color), so it reads as a note rather than part of the label, also when labels are gray.
- Multi-step forms no longer show "Your answers are saved as you go." under the buttons. Progress is still saved after each step; pass `<MultiStep notice="…" />` to show a line of your own.
- Checkboxes and radio buttons are drawn by Kibble instead of the browser, so they follow your theme: unchecked, the field background with the border color (no more gray browser fill in dark mode); checked, the primary color with the check or dot in the primary text color. The box is centered on the first line of its label at every size. They're styled by the `kb-check` class in `theme.css` and `styles.css`; in Windows high-contrast mode they fall back to the browser's own.

## 0.1.4 (2026-10-27)

**Where responses come from:**

- Responses now say which page on your site led to the form (`meta.referrer`, a path like `/pricing`), the first page of the visit (`meta.landingPage`) and the other site the visit came from (`meta.entryReferrer`, an origin), and campaign tags from the landing page when the form's page has none. Optionally, add `<KibbleAttribution />` to your root layout to record the pages before the form. Other sites are recorded as their origin only, never a path or query. Off with `createClient({ attribution: false })`. See [Attribution and hidden fields](https://api.trymirio.com/docs/attribution.md).
- Hidden fields and `prefill.query` read the visit's landing page when the form's page doesn't have the parameter.
- `meta.pageUrl` is now the page's origin and path: no query string (prefill links can carry answers there; campaign tags stay in `utm`) and no `#fragment`. Kibble trims it the same way for older versions.
- To follow in-site navigation, the client wraps `history.pushState` and `replaceState` (calling the originals) and listens for `popstate`. `createClient({ attribution: false })` leaves history alone.

- The thank-you card has a smaller, filled check mark (the primary color, with the check in its text color), a medium-weight title, and less space between its title and message.

**CLI:**

- `kibble destinations add slack --form <slug>` without a URL prints an "Add to Slack" link for a person to pick the channel, and waits for it (`--no-wait`, `--json`).
- `kibble status` and `kibble sync` say when a newer kibbleforms is out, at most once a day (`KIBBLE_NO_UPDATE_CHECK=1` turns it off).

**Kibble (no upgrade needed):** "Add to Slack" in the dashboard; webhooks and databases must be public addresses; spreadsheet formulas in CSV exports are neutralized; Slack and email notifications say where each response came from; Insights shows the pages that led to the form.

## 0.1.3 (2026-10-27)

**Changes how forms look:**

- Labels mark optional fields with a small, muted "Optional" and leave required fields unmarked (before: a red `*` on required fields). Screen readers hear "Optional" with the label; required controls still carry `aria-required`. To get asterisks back: `requiredIndicator={<span aria-hidden className="ml-0.5 text-kb-error">*</span>}` and `optionalIndicator={null}` on `Form` or `KibbleProvider`. See [Label](https://api.trymirio.com/docs/components/label-help-error.md).
- More room between a label and its control: `--kb-gap` is 0.5rem at `sm` and `md`, 0.625rem at `lg` (was 0.25, 0.375 and 0.5rem).
- A required `consent` checkbox follows `requiredIndicator` (no mark by default).

**CLI:**

- GitLab, CircleCI, Buildkite, Jenkins, Bitbucket Pipelines, Azure Pipelines and Travis are read by branch: production on `KIBBLE_PRODUCTION_BRANCH`, else the provider's default branch, else `main`; other branches and pull/merge requests register as preview. Before, they registered production on every branch.
- `init` at a monorepo root lists every app below it, Next.js and Astro before plain Vite, and asks you to pick the site.

**Docs:** a scroll offset for the success card under a fixed header ([Success](https://api.trymirio.com/docs/components/success.md)).

## 0.1.2 (2026-10-27)

- Inputs, selects and buttons keep the size's control height (`sm` inputs were 39px instead of 36px, buttons 37px).
- Render, Railway and any other build server that sets `CI` register forms as production. In 0.1.1 they registered as development.
- `init` only stops at a real repo root (no `package.json`, a workspace file, or no React), so a React site with a Vite storybook folder sets up normally; `--force` skips the check.
- `domains add` names the www twin from the hostname, and none for a wildcard, `localhost` or an IP.

## 0.1.1 (2026-10-27)

- A build with no deploy host (a local `next build`) registers forms as development, not production.
- The success card takes focus and scrolls into view when it replaces the form.
- `init` stops at a monorepo root before using a link code, matches the install hint to your package manager, maps shadcn colors only when the site has shadcn's variables, and writes an AGENTS.md section that matches the site (live or sandbox, the styles it set up).
- The shadcn theme files fall back to Kibble's colors when a variable is missing.
- `kibble --version` prints the package's version.

## 0.1.0 (2026-10-26)

First release: the `Form` components and headless hooks, the typed schema, the client, and the `kibble` CLI (`init`, `sync`, `push`, `test`, `status`, `claim`, `domains`, `destinations`, `review`, `submissions`, `env`).