TextField

<caos-text-field>

single-line text input with type validation

May be placed on a record page, a page inside an app and a step of a guided flow.

Inputs

Name	Attribute	Description	Type	Default	Required
label	label, markup only	The field’s name, drawn above the control and pointed at the input, so clicking it focuses the box. Left unset, no label is drawn at all.	text	none declared	Optional
placeholder	placeholder, markup only	The greyed hint inside an empty box. A hint, never a substitute for the label.	text	none declared	Optional
value	value, markup only	The current text. It is written back to this attribute on every keystroke, so the attribute and what is on screen stay the same thing.	text	none declared	Optional
name	name, markup only	The form name forwarded to the inner input, for a field submitted as part of a form.	text	none declared	Optional
required	required, markup only	This field has to be filled in. Draws the asterisk beside the label and marks the inner input required.	boolean	false	Optional
disabled	disabled, markup only	You may not type in this. Greys the box and refuses focus.	boolean	false	Optional
invalid	invalid, markup only	What is in the box is wrong. Turns the border and the message red and marks the input invalid for a screen reader. It does not itself decide anything is wrong — the page sets it.	boolean	false	Optional
message	message, markup only	The line under the box. Muted helper text on its own; the same line turns red and reads as the reason when invalid is also set.	text	none declared	Optional
format	format, markup only	The Text format this field is drawing, named as the kernel names it: long for several lines, and email, phone or url for a single line that asks for the right keyboard and lets the browser check the shape of what is typed. A field in no format is a plain one-line box. The field renderer passes whatever the field declared, so honouring a format is not something a page has to remember to ask for.	text — recognises long, email, phone, url; anything else reads as plain	none declared	Optional
maxlength	maxlength, markup only	The longest value this field accepts, which is the length the field declared. Enforced by the control, so the reader is stopped at the limit rather than having the end of what they typed removed somewhere below. Applies in one line and in several alike. With none declared the field is unbounded.	number	none declared	Optional
multiline	multiline, markup only	Draw the value as several lines instead of one. This is the Text kind’s declared long format, not a second field: the label, the value, the validity, the message and every event mean exactly what they mean in one line. A field given format=“long” draws several lines whether or not this is also set, so the two cannot disagree; the field renderer sets the format and a page placing this field directly is the only caller that reaches for this instead. The reader can drag the control taller but not wider — a box that can be dragged wider tears the form column out of shape.	boolean	false	Optional
inline	inline, markup only	Draw the record-detail variant instead of the boxed form control: no box, an accent underline, inheriting the surrounding type. The label and the message are hidden, because the surrounding record detail supplies the field name.	boolean	false	Optional

Events

Name	When it fires	What it carries
input	On every keystroke, after the value attribute has been written back.	nothing
change	When the control is committed — focus leaves, or Enter is pressed.	nothing

Slots

Nothing goes inside this piece.

Styling hooks

Design token	What it controls
--caos-font	The typeface of the label, the box and the message.
--caos-text-body	The size of the label and of the typed text.
--caos-space-1	The gap between the label, the box and the message.
--caos-space-3	The vertical padding inside the box.
--caos-radius	The corner radius of the box.
--caos-color-border	The box outline at rest.
--caos-color-border-strong	The box outline while the field has focus.
--caos-color-surface-2	The fill of the box.
--caos-color-text	The colour of the typed text.
--caos-color-text-muted	The label, the placeholder, the message and disabled text.
--caos-color-accent	The hover outline, and the underline of the inline variant.
--caos-accent-wash	The tint that fills the box while it has focus, in place of a focus ring.
--caos-color-danger	The required asterisk, and the outline and message when invalid.

Methods

Name	Description	Arguments
focus()	Put the caret in the box and select what is already there. The record-detail editor calls it when a value is clicked to edit, so typing replaces rather than appends.	options: FocusOptions

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
::part(label)	the label above the control	Always
::part(input)	the inner text input — or the text area, in the multiline format; one part name, because it is one control	Always
::part(message)	the line under the control	Always

When to use it

A single line of free text the person types themselves. If the value is one of a known set, or a number, or a date, one of the siblings below is the field that already knows that.

What to use instead

• FieldRenderer — The type is not known until the record is read — hand it the field metadata and it draws the right control.
• NumberField — The value is a number, so it should align in tabular figures and take min/max/step.
• DateField — The value is a calendar date and should offer the platform date picker.
• PicklistField — The value is one of a fixed list rather than anything the person types.
• LookupField — The value points at another record rather than being text of its own.
• InlineHint — You only want the explanatory line and there is no value being edited.

Accessibility

The control is a real input with a generated id, and the label points at it, so it is announced with its name and clicking the label focuses the box. required and invalid are forwarded to the input as required and aria-invalid. Focus is shown as a wash inside the box rather than a ring, which is the platform treatment. What is left to the author is the label text itself — an unlabelled field is announced as an unnamed text box — and the wording of the message, which is the only thing that says WHY the field is refused.

Examples

Labelled, with a hint

The ordinary form field: a name above it and a greyed example inside it.

{
  "id": "example",
  "section": "Labelled, with a hint",
  "columns": 1,
  "items": [
    {
      "id": "text_field_1",
      "type": "component",
      "key": "text_field",
      "inputs": {
        "label": "Project name",
        "placeholder": "e.g. North region rollout"
      }
    }
  ]
}

<caos-text-field label="Project name" placeholder="e.g. North region rollout"></caos-text-field>

Required, refused, and locked

The three states a page sets on a field it is validating, side by side — the asterisk, the red outline with its reason, and a field that may not be typed in at all.

{
  "id": "example",
  "section": "Required, refused, and locked",
  "columns": 1,
  "items": [
    {
      "id": "text_field_1",
      "type": "component",
      "key": "text_field",
      "inputs": {
        "label": "Project name",
        "required": true,
        "value": "North region rollout"
      }
    },
    {
      "id": "text_field_2",
      "type": "component",
      "key": "text_field",
      "inputs": {
        "label": "Reference",
        "invalid": true,
        "value": "R-1",
        "message": "A reference is at least four characters."
      }
    },
    {
      "id": "text_field_3",
      "type": "component",
      "key": "text_field",
      "inputs": {
        "label": "Order number",
        "disabled": true,
        "value": "ORD-4471"
      }
    }
  ]
}

<caos-text-field label="Project name" required value="North region rollout"></caos-text-field>
<caos-text-field label="Reference" invalid value="R-1" message="A reference is at least four characters."></caos-text-field>
<caos-text-field label="Order number" disabled value="ORD-4471"></caos-text-field>