Build a dictation box

Follow along with the runnable example. This guide walks through the Dictation box example in corti-examples — bootstrap your build from it or use it as reference.

A dictation box is a classic speech-enabled-app workflow: dictate into a scratch box, refine the text, then transfer it into whichever form field you were working in, and navigate the form by voice along the way. A single microphone drives the whole thing. This guide combines two earlier building blocks: caret Text Insertion through an EditorAdapter, and the Commands declare → event → dispatch loop. The new idea is routing — deciding which control each dictation segment lands in.

The commands

The workflow is driven by a small command set: two to control routing, one to transfer, and two to navigate the form.

Command	Effect
`show dictation box`	Focus the scratch box
`target dictation box`	Route dictation into the box without moving focus
`transfer text`	Insert the box’s text into the last-active field, then clear it
`go to {field}`	Focus a text field, or open a dropdown
`pick {number}`	Select the Nth option in the open dropdown

JavaScript

const BOX_COMMANDS = [
  { id: "show_dictation_box",   phrases: ["show dictation box", "show the dictation box"] },
  { id: "target_dictation_box", phrases: ["target dictation box", "target the dictation box"] },
  { id: "transfer_text",        phrases: ["transfer text", "transfer the text"] },
  {
    id: "go_to_field",
    phrases: ["go to {field}", "go to {field} field"],
    variables: [{ key: "field", type: "enum", enum: ["note one", "note two", "severity"] }],
  },
  {
    id: "pick_option",
    phrases: ["pick {number}", "choose {number}", "option {number}"],
    variables: [{ key: "number", type: "enum", enum: ["one", "two", "three", "1", "2", "3"] }],
  },
];

Route dictation to the right target

By default, final dictation inserts at the caret of whatever control is focused — exactly like typing. The one exception is the box-target override: after target dictation box, dictation goes into the scratch box while the form field keeps its focus and caret.

JavaScript

// On each final segment, route to the box or the active field.
if (targetBox) {
  // Override: route into the scratch box; focus stays on the form field.
  boxAdapter.insert(segment, { primaryLanguage: "en" });
} else {
  // Default: insert at the caret of the focused control.
  activeAdapter.insert(segment, { primaryLanguage: "en" });
}

To make transfer text work, track the last-active field that isn’t the box — that’s the transfer destination. A focusin listener records it, and focusing any field clears the override.

JavaScript

container.addEventListener("focusin", (e) => {
  const el = e.target;
  if (el === boxEl) return;              // ignore the box itself
  lastFieldRef.current = adapterFor(el); // remember the transfer destination
  if (targetBox) setTargetBox(false);    // focusing a field cancels the override
});

Transfer the box into a field

transfer text inserts the box’s contents at the caret of the last-active field — reusing the same boundary-aware insert — then clears the box and the override.

JavaScript

function transfer() {
  const text = boxEl.value;
  if (!text) return;
  lastFieldRef.current?.insert(text, { primaryLanguage: "en" });
  boxEl.value = "";
  setTargetBox(false);
}

Navigate the form by voice

go to {field} focuses a text field (caret to end) or opens a dropdown. pick {number} selects an option — parse the spoken value so both "two" and "2" resolve to the same 1-based index.

JavaScript

const WORDS = ["one", "two", "three", "four", "five", "six"];

function parseOrdinal(value: string): number | null {
  const v = value.trim().toLowerCase();
  const digit = Number.parseInt(v, 10);
  if (Number.isFinite(digit) && digit > 0) return digit;
  const word = WORDS.indexOf(v);
  return word === -1 ? null : word + 1;
}

A native <select> can’t be opened or selected-by-index programmatically, so dropdown fields need a custom listbox (a button + option list) exposing an imperative open/pick handle. Text fields work directly through the EditorAdapter.

Next steps

Text Insertion

The caret-insertion EditorAdapter that box and field writes reuse.

App Control

Drive non-text UI — tabs, panels, dialogs — by voice.

Example code

The complete, runnable Dictation box example in corti-examples.

Please contact us for help or questions.

Endpoints

Features

Best Practices

Guides

Resources

The commands

Route dictation to the right target

Transfer the box into a field

Navigate the form by voice

Next steps

Text Insertion

App Control

Example code

​The commands

​Route dictation to the right target

​Transfer the box into a field

​Navigate the form by voice

​Next steps

Text Insertion

App Control

Example code

The commands

Route dictation to the right target

Transfer the box into a field

Navigate the form by voice

Next steps