Input

Input component for entering content via keyboard, the most basic form control.

Use when you need a text field with a static top-aligned label, leading icon, validation status/message, and native form participation: <r-input> covers text, password, and number entry.

Quick Start

Basic Usage

<r-input placeholder="Enter text"></r-input>

API Reference

Properties

Property	Type	Default	Description
`label`	`string`	`''`	Static caption rendered above the field
`placeholder`	`string`	`''`	Placeholder text, forwarded to the native `<input>`
`value`	`string`	`''`	Field value; reflected as an attribute and relayed to the form
`disabled`	`boolean`	`false`	Whether the input is disabled
`type`	`string`	`''`	Native input type forwarded to the inner control (`text`, `password`, `number`, …)
`icon`	`string`	`''`	Leading icon name (rendered as `r-icon`) inside the field
`name`	`string`	`''`	Form field name used when the input participates in a form
`status`	`string`	`''`	Validation status: `error`, `warning`
`message`	`string`	`''`	Helper / validation text rendered below the field
`min`	`string`	`''`	Minimum value; forwarded to the inner `<input>` when `type="number"`
`max`	`string`	`''`	Maximum value; forwarded to the inner `<input>` when `type="number"`
`step`	`string`	`''`	Value step; forwarded to the inner `<input>` when `type="number"`
`required`	`boolean`	`false`	Forwarded to the inner `<input>` so native constraint validation applies
`sheet`	`string`	`''`	CSS injected into the shadow root

A static caption rendered above the field: always visible, never overlaps adjacent content, and doesn't shift the layout on focus (top-aligned labels also complete forms faster than inline/floating ones; see Luke Wroblewski's eye-tracking research).

<r-input label="Username"></r-input>

The label, control and helper occupy separate rows. When the host has an explicit height, the control fills the space left by its label and helper while retaining its minimum height.

Placeholder `placeholder`

Consistent with the native placeholder attribute.

<r-input placeholder="Enter username"></r-input>

Value `value`

<r-input value="1234"></r-input>

Disabled State `disabled`

<r-input label="Username" disabled></r-input>

Icon `icon`

A leading icon composes with the static label. Adding or changing icon keeps the visible caption and native label association.

<r-input icon="user"></r-input>

Input Types `type`

<r-input icon="lock" type="password" placeholder="Password"></r-input>
<r-input type="number" placeholder="Number"></r-input>

Status `status`

Pair status with a message so the state is conveyed by text, not color alone.

Status labels and helper text use --ran-color-warning-foreground and --ran-color-danger-foreground. These follow the text color scale in both themes, while --ran-color-warning and --ran-color-danger retain their solid-fill roles. Existing component label/message color overrides still apply.

<r-input status="error" label="Username" message="This field is required"></r-input>
<r-input status="warning" label="Username" message="Check this value"></r-input>

Helper Message `message`

Renders helper / validation text below the field.

<r-input label="Email" message="We will never share your email"></r-input>

Form Field Name `name`

<r-input name="username" label="Username"></r-input>

Events

Both events are dispatched as CustomEvents carrying the current value in detail.

Event	When it fires	`detail`
`input`	On every keystroke (mirrors the native `input`)	`{ value: string }`
`change`	On commit / blur (mirrors the native `change`)	`{ value: string }`

Input Event `input`

const input = document.createElement('r-input');
input.setAttribute('label', 'Username');
input.addEventListener('input', (event) => {
  console.log('Typing:', event.detail.value);
});

Change Event `change`

const input = document.createElement('r-input');
input.setAttribute('label', 'Username');
input.addEventListener('change', (event) => {
  console.log('Value changed:', event.detail.value);
});

Form Association

r-input is a form-associated custom element (static formAssociated = true). It attaches ElementInternals and relays its value via setFormValue, so the field is collected by new FormData(form) when it's a real descendant of a native <form>; set name to give the value a key. See Forms for the serializeForm() helper that turns a submit into a plain object.

<form>
  <r-input name="username" label="Username"></r-input>
</form>

Reset: a native form.reset() (or <button type="reset">) restores the value the field had when it first connected, implemented via formResetCallback(), one of the lifecycle hooks the browser calls automatically on a form-associated custom element.

Validation: the native control's validity is relayed through ElementInternals.setValidity(), including required, email format and number min/max/step constraints. form.checkValidity()/form.reportValidity() see it, and submitting shows the browser's native validation bubble anchored on the field. disabled fields never block validation, matching native <input>. r-input also exposes the usual native-field methods/properties: checkValidity(), reportValidity(), validity, validationMessage.

Changing or removing value, type, disabled and numeric constraint attributes after mounting updates the native control and form state. The label is always plain text, including when updated.

<form>
  <r-input name="username" label="Username" required></r-input>
  <button type="submit">Submit</button>
</form>

CSS Parts

Exposed via ::part() for external styling.

Part	Element
`input`	The field wrapper
`content`	The inner native `<input>` control
`label`	The static label above the field (present when `label` set)
`message`	The helper / validation text (present when `message` set)

r-input::part(content) {
  font-size: 16px;
}

Styling

<r-input> exposes 61 CSS custom properties of its own, plus the semantic tokens it reads from the theme. Set one anywhere it inherits from, such as :root, a wrapper, or the element:

r-input {
  --ran-input-color: var(--ran-color-text-secondary);
}

Parts: content · input · label · message

The full list is in style tokens; which token to use is in the design system.

Best Practices

Labels: Add a meaningful label so the field has an accessible name.
Placeholders: Use placeholder for input hints, not as a replacement for a label.
Status + Message: Pair status with message so state is not signalled by color alone.
Icons: Add a relevant icon to enhance recognition.
Types: Choose the appropriate type (text, password, number, …) for the content.
Forms: Set name when collecting the value inside a form.