Documentation

Documentation

Input

Form-associated text field with a label, error message, and native validation.

The <dsgn-input> component renders a labelled text field. It is form-associated, so its value reaches an enclosing <form> — through FormData and through native constraint validation — even though the real <input> lives in the shadow root.

The Public Beta supports two input types: text and email.

Usage

<dsgn-input
  label="Email"
  type="email"
  name="email"
  placeholder="you@example.com"
></dsgn-input>

Import the component module in your application entrypoint:

import '@ds-gn/ui/input';

Playground

Props

Prop Type Default Description
type 'text' | 'email' 'text' Input type. Password, number, tel, and url are not supported yet.
label string '' Label text rendered above the field. Omitted when empty.
placeholder string '' Placeholder shown while the field is empty.
value string '' Current value. Deliberately not reflected — the attribute stays the authored default.
name string '' Field name submitted with the form. Reflected, so a value set only as a property still lands in FormData.
size 'sm' | 'md' | 'lg' 'md' Control size.
error string '' Error message shown below the field. A non-empty value also switches the field to its error styling.
aria-label string '' Accessible name for the inner <input>, for fields with no visible label.
disabled boolean false Disables the field.
required boolean false Marks the field required for constraint validation.
surface 'light' | 'dark' 'light' Semantic token surface to use.

aria-label is the attribute name; the matching JavaScript property is ariaLabel.

Slots

The component renders its own label, input, and error message, and takes no slotted content.

Events

Event Detail Description
dsgn-input { value, name } Fired on every value change. Bubbles and crosses the shadow boundary.

In React, the generated wrapper exposes this as onDsgnInput.

Methods

Method Description
formResetCallback() Called by the platform when the owning form resets. Clears value and error and restores validity.
formDisabledCallback(disabled) Called by the platform when a <fieldset disabled> or form owner toggles the inherited disabled state.

Both are form-association lifecycle callbacks. The browser calls them — you do not.

Forms

<form>
  <dsgn-input name="email" type="email" label="Email" required></dsgn-input>
  <dsgn-button type="submit">Subscribe</dsgn-button>
</form>
form.addEventListener('submit', (event) => {
  event.preventDefault();
  const email = new FormData(form).get('email');
});
  • Validity is mirrored from the inner <input> to ElementInternals, so a required or type="email" field blocks submission the way a native one does.
  • Inherited disabled state (for example from a <fieldset disabled>) is tracked separately from the disabled property, so re-enabling the fieldset restores the field.
  • A form reset clears both the value and any error message you set.

Examples

Sizes

<dsgn-input label="Small" size="sm"></dsgn-input>
<dsgn-input label="Medium" size="md"></dsgn-input>
<dsgn-input label="Large" size="lg"></dsgn-input>

Error message

<dsgn-input
  label="Email"
  type="email"
  error="Enter a valid email address."
></dsgn-input>

Listening for changes

document.querySelector('dsgn-input').addEventListener('dsgn-input', (event) => {
  const { value, name } = event.detail;
});

No visible label

<dsgn-input aria-label="Search" placeholder="Search…"></dsgn-input>

Disabled

<dsgn-input label="Read only" value="Cannot edit" disabled></dsgn-input>

Dark surface

<dsgn-input label="Email" surface="dark"></dsgn-input>

Accessibility

  • Prefer a visible label. When the design has no room for one, set aria-label so the field still has an accessible name — a placeholder is not a label.
  • error is rendered as visible text below the field. Keep the message specific enough to act on, and set it alongside the field’s invalid state rather than in place of it.
Esc