Appearance
TextInput and TextArea
TextInput is one line of text with a name above it and a message under it. TextArea is the same component with multiline on: one implementation, because there is one behaviour, and the only difference an application sees is what Enter does. Reach for either wherever someone types free text; a quantity belongs in NumberInput, which parses and steps.
The email field is controlled and the nickname field is not. Type into each, then press the button: it writes the cell the email field is bound to, and the field follows without anything having been typed.
tsx
/**
* Three fields, and the two ways a value can be owned.
*
* **Email is controlled.** The application holds the string; the field
* shows what it is given and reports what was typed. The button writes
* the cell from outside, which is the ownership being visible rather
* than claimed: nothing was typed and the field still moved.
*
* **Nickname is uncontrolled.** One `defaultValue` and no `onChange`,
* so the control keeps its own text. No cell in this component holds
* it and the line at the bottom cannot see it.
*
* **Notes is a `TextArea`**, which is `TextInput` with `multiline` on.
* The difference that matters is Enter: in the single-line field it is
* the form's, and calls `onSubmit`; here it belongs to the text.
*/
export function TextFields(_inputs: Inputs<{}>, _ctx: ComponentContext) {
const email = internalState('');
const notes = internalState('');
const sent = internalState(false);
// An error is a string, and an empty one is no error: the field goes
// back to showing its description and drops the `invalid` state.
const error = email.pipe(map(value => (value.length === 0 || value.includes('@') ? '' : 'An address needs an @')));
const status = combineLatest([email, notes, sent]).pipe(
map(([address, body, done]) =>
done ? `Sent ${body.length} characters to ${address}` : `${body.length} characters, not sent`
)
);
return (
<column gap={12} padding={20} width={percent(100)} height={percent(100)}>
<TextInput
label="Email"
placeholder="you@example.com"
description="Enter submits it."
required
value={email}
error={error}
onChange={next => {
email.value = next;
sent.value = false;
}}
onSubmit={() => (sent.value = true)}
/>
<button
label={`Use ${ADDRESS}`}
onClick={() => {
email.value = ADDRESS;
sent.value = false;
}}
padding={8}
borderRadius={6}
borderWidth={1}
borderColor="border"
backgroundColor="background"
cursor="pointer"
modifiers={[HOVER_CONTROL]}>
<text text={`Use ${ADDRESS}`} fontSize={12} color="text" />
</button>
<TextInput label="Nickname" defaultValue="ada" description="This one keeps its own text." />
<TextArea
label="Notes"
placeholder="Enter starts a line."
value={notes}
onChange={next => (notes.value = next)}
/>
<text text={status} fontSize={12} color="textMuted" />
</column>
);
}Props
TextAreaProps is TextInputProps without multiline and secret; everything else on this table is shared.
| Prop | Type | Default | What it does |
|---|---|---|---|
value | string | none | The text to show. Supplying it makes the field controlled. |
defaultValue | string | '' | The text to start with, for a field that owns its own value. Supplying both throws, naming the component. |
onChange | (value: string) => void | none | Called with the whole new text after every edit. |
label | string | '' | Drawn above the field and used as its accessible name. An empty label draws nothing. |
labelHidden | boolean | false | The label still names the field but is not drawn: for a search field whose placeholder and place already say what it is. |
placeholder | string | none | Drawn in the field while it is empty, and measured: an empty field is at least as wide as its placeholder. |
description | string | '' | Drawn under the field, and announced after the name. An error replaces what is drawn. |
error | string | '' | A non-empty string marks the field invalid, turns its border to the danger token, and shows this message under it in place of the description. |
disabled | boolean | false | Refuses focus, so the field is not a tab stop and takes no edits, and draws the label in the disabled foreground token. |
readOnly | boolean | false | Takes focus, and allows the caret, selection and copying, but refuses every edit. Announced as readonly. |
required | boolean | false | Announced as required. It validates nothing on its own; the message is error's job. |
multiline | boolean | false | Wraps the text instead of scrolling it, raises the field's minimum height from 32 to 72, and hands Enter to the text. TextArea sets it, and drops it. |
secret | boolean | false | A password field. See Secret fields. |
onSubmit | () => void | none | Called on Enter in a single-line field, and on Command-Enter or Control-Enter in a multiline one, where Enter alone is a new line. |
ref | UiNodeRef | none | Receives the node that is the field, which is what a form focuses and an overlay anchors to, rather than the component's outer column. |
Layout and modifiers
The shared layout props land on the component's root, and rootModifiers attaches to the element that is the field, which is what a measure needs in order to see the real geometry. There are no colour props: the field reads the theme.
A field is a window on its text rather than a label. In a row it shrinks to the space it is given and scrolls or wraps inside, and it passes no minimum width up to its parent, so a row does not push its other children narrower with every character typed.
Controlled and uncontrolled
Hand the field value and it shows what the application gives it; hand it defaultValue and it keeps its own text:
tsx
<TextInput label="Email" value={email} onChange={next => (email.value = next)} />
<TextInput label="Email" defaultValue="you@example.com" />Which form applies is decided once, when the component is built, from whether value was supplied; supplying both throws.
The keystrokes themselves land in the field's own model, on the node, in the render worker. That is what keeps the caret off the round trip through the application: nothing waits for a value to be echoed back. value is applied whenever it differs from the last string the field took, so an application that writes every reported value straight back controls the field and disturbs nothing, and one that writes a different string replaces the text.
Two consequences worth knowing before you write a transform in onChange:
- Writing a different string back resets the field's undo history. As far as the model is concerned, the text it replaced never existed.
- A field handed
valueand noonChangestarts at that value and keeps what is typed, as adefaultValuewould; the next value the application hands it lands in the field. A field only the application may change isreadOnly.
What the field brings with it
Editing is not a prop, it is what an EditableText node is, so all of this arrives with the component and none of it is yours to write:
- A caret, blinking on the runtime's timer, drawn where the paragraph layout puts it. Layout, both renderers and the caret break lines through the same measurer, so the caret cannot land between two characters the renderer drew somewhere else.
- A selection. A press places the caret and Shift extends to it, a second press selects the word, a third the line, and a drag afterwards extends from the anchor.
- Grapheme steps. Moves and deletes step by grapheme through
Intl.Segmenter, with a surrogate-pair fallback, so the caret never splits an emoji. Word boundaries come from the same segmenter, which is what makes a CJK word a word. - An undo stack that coalesces a run of typing, a run of backspaces, or a whole composition into one entry.
- IME composition. The shell keeps a hidden
<textarea>focused at the caret. It empties itself when a composition starts, so the candidate window opens at the caret rather than at the corner of the page, reports the composition as it is built and the result when it commits, and both renderers draw the composition underline. The caret holds steady rather than blinking while a composition is open. - The clipboard. Copy, cut and paste are the platform's own, handled on the main thread against the runtime's text, because the clipboard is reachable only from a user gesture there. Newlines pasted into a single-line field become spaces.
- Scrolling that follows the caret. A single-line field scrolls its text rather than wrapping it, and follows the caret, which is what a text field does. The wheel scrolls a field that overflows as well, without moving the caret, and a multiline one shows an overlay scrollbar while it scrolls.
What is not here: a maxLength, and drag-and-drop of text.
Where this was checked. The editing path was verified by hand in Chrome on Linux. WKWebView and WebView2 are not covered, and mixed left-to-right and right-to-left runs inside one line are not reordered: textDirection: 'rtl' mirrors a line, and hit testing is direction-aware rather than fully bidirectional. On a touchscreen, the shell re-asserts focus on the pointerup of the press that opened a field, which is the gesture a phone raises its keyboard for; that path is covered by unit tests against a fake DOM and by synthetic touch pointers in Chrome, and has not been run on a physical device.
Secret fields
secret makes the field a password field, for a password, a passphrase or a token:
tsx
<TextInput label="Passphrase" secret={true} value={passphrase} onChange={next => (passphrase.value = next)} />It behaves as a browser's <input type="password"> does. Every character is drawn as a bullet, one for each UTF-16 code unit, so a character outside the Basic Multilingual Plane draws as two; the caret, the selection and a click all work on the bullets. The placeholder is drawn as it is. onChange gets the real text. Copy and cut take nothing and leave the clipboard as it was; paste works. A word move or delete goes to the end of the text, and a double click selects all of it, so the caret shows nowhere a word ends.
While the field has focus the shell edits it through a hidden <input type="password"> in place of the textarea, so the browser and the platform treat it as a password: macOS turns on secure input, nothing autocorrects or remembers it, and a screen reader calls it a secure text field. The text itself stays in the render worker. The shell's element, the semantics record and the accessibility mirror hold only the bullets.
A secret field is one line. multiline is ignored while secret is on, and Enter calls onSubmit.
Keyboard
The map is the platform's. On a Mac, Command jumps to the ends of a line and of the text, and Option steps by word; everywhere else Control does both. The platform is detected once from the user agent, in the worker as readily as on the main thread.
| Key | What it does |
|---|---|
| Left, Right | Move the caret one grapheme |
| Word modifier, Left/Right | Move it one word |
| Command, Left/Right | Move it to the start or end of the visual line (Mac) |
| Up, Down | Move up or down one visual line, keeping the caret's x |
| Command, Up/Down | Move to the start or end of the text (Mac) |
| Home, End | The start or end of the visual line |
| Control, Home/End | The start or end of the text |
| Backspace, Delete | Delete one grapheme back or forward; with the word modifier, one word |
| Command, Backspace | Delete to the start of the line (Mac) |
| Enter | Single line: calls onSubmit. Multiline: inserts a newline |
| Command or Control, Enter | Calls onSubmit, in a multiline field as in a single-line one |
| Primary, A | Select all |
| Primary, Z | Undo; with Shift, redo. Control+Y also redoes off a Mac |
| Tab | Leaves the field. Nothing here captures it, in a TextArea either |
Shift extends the selection on every move above rather than collapsing it. "Primary" is Command on a Mac and Control elsewhere. A key the application handles first and marks handled never reaches this map: the field's editing is a default behaviour, and onKeyDown runs ahead of it, which is exactly how onSubmit takes Enter away from the text.
In a multiline field Enter is the text's, so onSubmit is reached with Command or Control held, either one on every platform, which is the convention a comment box or a chat composer has already taught. Without a modifier, Enter goes on inserting a newline.
Semantics
The field, not the column around it, is the node in the semantics tree. It emits:
role:textbox, for both components.multilinechanges what Enter does, not what the control is.label: thelabelprop. This is why the name is not written twice: the text drawn above the field is the same string the accessible name comes from.description: thedescriptionprop.valueText: the text in the field, taken from the node'svaluerather than declared, because an editable's content is its value and not its name. Asecretfield's is its bullets, which say how long the text is and nothing else.states:invalidwhileerroris a non-empty string,requiredwhilerequiredis set,readonlywhilereadOnlyis. Disabled is not a state but a flag of its own on the record.
The message under the field carries its own text into the tree, so an error is readable there. The field's description stays whatever description said; what tells an assistive technology that something is wrong is the invalid state.
That is what the spec beside the example queries, and it is the same tree the accessibility mirror hands the platform. There is no second definition of what this control is.
Following the caret
onInput says the text changed. It says nothing about the caret, which moves without the text on every arrow key, every click into the text and every select-all. onSelectionChange is the other half:
tsx
<editabletext
value={formula}
onInput={event => setFormula(event.value)}
onSelectionChange={event => setCaret(event.focus)}
/>It carries the text as well as the offsets, because every use of it is "what is under the caret" and reading the text back afterwards is a second source of truth that can disagree by a frame. start and end are ordered; anchor and focus say which end was begun at and which the caret is on. It is skipped when the selection did not actually move, so holding a key against the end of the text is silent, and skipped entirely when nothing is listening.
When both happen, onInput fires first, so a listener reading the value sees the new one.
Putting something at the caret
A popup under the word being typed needs to know where the caret is on screen, and an application cannot work that out: the geometry depends on the paragraph as it was laid out, so re-measuring the text would be a second measurer that must never disagree with the engine's. Ask instead.
tsx
const editing = ctx.inject(EditingService);
const caret = editing.caretRectOf(fieldNode);The rectangle is in the field's own coordinates, with the field's scroll already applied. It is null for a node that is not a field and for one that has not been laid out yet. Both happen in the frame a field first appears, and both mean ask again next frame.
A second argument asks about another character than the one the caret is on. A list of names opened by @ belongs under the @, not under the caret, which moves on as the name is typed:
tsx
const at = editing.caretRectOf(fieldNode, start); // where the @ is
list.show(content, {
anchor: fieldNode,
anchorRect: { x: at.x, y: at.y, width: 0, height: at.height },
placement: 'bottom-start'
});Given as the overlay's anchorRect, with the field as its anchor, the list follows the field through scrolling like any anchored overlay. A point would stay where it was put. anchorRect can be an Observable too, so the list moves with its word when the word wraps onto the next line, without opening again.
The other way round, offsetNear says which character a point is nearest, as a press there would put the caret. A field opened over text the person pointed at, to change it in place, starts its caret where they pointed: ask once the field is laid out, then select there.
tsx
const offset = editing.offsetNear(fieldNode, pointer.x, pointer.y);
if (offset !== null) {
editing.select({ node: fieldNode, offset }, { node: fieldNode, offset });
}The point is given as a pointer event gives it. Like caretRectOf, it answers null until the field is laid out.
Next
Slider and NumberInput are the same contract over a number, and Using components is the shorter tour of the library these three come from.