QsInput

<qs-input>alpha

A single-line text or number field. A <label for> names the native <input id>; an optional hint inside the label says what to enter, and an error line below explains what's wrong. Native validation (required, number checks) runs on blur and on submit, and the value is submitted with its form under name.

Examples

<qs-input label="Project name" name="project" hint="Lowercase letters and dashes"></qs-input>
<qs-input label="Quantity" type="number" name="qty" value="1" required></qs-input>
<qs-input label="Slug" name="slug" error="Use lowercase letters and dashes only"></qs-input>

Prop

Prop	Type	Default	Description
label	string	""	Visible label, also the field's accessible name. Required.
hint	string	""	Suggestion of what to enter (format, unit, example), shown inside the label under its text, so it is read as part of the field's name.
error	string	""	Error message, e.g. from the server. Marks the field invalid (it blocks its form) until you clear it. Without it, the browser's own message is shown when native validation fails.
type	"text" | "number"	"text"	Kind of value. Anything else falls back to `text`.
name	string	""	Name the value is submitted under in a form.
value	string	""	Current value. Kept in sync as the user types.
required	boolean	false	The field must be filled before its form submits. Shown as "(required)" next to the label.
disabled	boolean	false	The field can't be focused or edited, and isn't submitted.
text	string	—	The text content of the element, captured from light DOM before the first render.

Usage

Use an input for one line of free text or a number. Every input has a visible label; never rely on placeholder text to say what goes in the field.

Text and number

type="text" (the default) takes any characters. type="number" takes numbers only, opens the numeric keyboard on phones, and supports the arrow keys to step the value.

Hint

hint suggests what to enter: a format, a unit, an example. It sits inside the label, under the label text, so screen readers read it as part of the field's name ("Project name, Lowercase letters and dashes"). Keep it short; it is read every time the field gets focus.

Errors and validation

Native validation runs when the field loses focus and when its form is submitted: an empty required field, or text in a type="number" field, shows the browser's message under the input with a warning icon, a red border and aria-invalid="true". The message clears as soon as the value is fixed.

Set error for a message of your own, for example one returned by the server. It is shown the same way, marks the field invalid so the form won't submit, and stays until you clear it.

<qs-input label="Slug" name="slug" error="This slug is already taken"></qs-input>

Required

required adds "(required)" next to the label and stops the form from submitting while the field is empty. Screen readers announce "required" from the native attribute.

Disabled

disabled greys the field out; it can't be focused or edited and its value isn't submitted. Prefer explaining why something can't be changed over disabling it silently.

In a form

The native input sits inside the component, so it submits with its form under name, and input and change events bubble from qs-input. Read the current value from the value property.

<form>
  <qs-input label="Email" name="email" required></qs-input>
  <qs-button variant="primary">Subscribe</qs-button>
</form>

Do and don't

• Do write labels that name the value: "Quantity", not "Enter a number here".
• Do use type="number" only for amounts; phone numbers, postcodes and IDs stay text.
• Don't hide the label or replace it with a placeholder.

Accessibility

• Renders a <label for> pointing at the native <input id> (a unique id per field): the label, hint included, is the accessible name, and clicking it focuses the field.
• An error is linked with aria-describedby and the field gets aria-invalid="true"; it is shown with text, an icon and a border, never colour alone. Error text passes 4.5:1 in both themes.
• required is the native attribute; the visible "(required)" text is aria-hidden so it isn't read twice.
• Focus shows the ring from the --focus-outline-* tokens.
• The border passes 3:1 and the text 4.5:1 against the field background in both themes.
• No motion.