Input — DS-GN Docs

Open this component in Storybook

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.