Text Fields - National Design System

Server-rendered Errors

A server-rendered page paints its own errors on load. Loop over the errors from the server, call setStatus for each field, then focus the first one. setStatus sets the status and inserts the message, but it never moves focus — only the caller knows which error comes first. Focus also scrolls the field into view, so an error below the fold reaches the user.

The data-feedback-target element sets where a field's feedback renders. It is optional: without one, the API creates feedback in the field's container. Place it anywhere inside the container — a nds-form-footer puts messages below the input, a nds-form-header puts them above. A hidden target is shown when a message lands and hidden again when the last message clears.

Best Practices

• Use form inputs for any data collection scenario: registration flows, search interfaces, settings pages, and inline editing. Every input type shares the same container structure, so switching between text, email, password, or select requires minimal markup changes.
• A nds-form element draws no box of its own — it is a validation hook, not a layout container. Give its fields a gapped wrapper: nds-card-content or nds-flex nds-col. Fields in a bare container render flush against each other.
• Use nds-search-input for search fields where voice input and automatic clear actions improve discoverability. The search variant includes a leading icon and optional microphone button out of the box.
• Wrap a form's submit and navigation buttons in nds-form-actions. The plural class is the form-level row and carries its own top margin. The singular nds-form-action is the per-input slot inside nds-form-control. Never use a section action slot for a form's buttons.
• Use the custom select dropdown (nds-select) for in-form choice fields, whatever the option count — a native select beside styled fields breaks the form's look. It ships with keyboard navigation and a hidden input so it submits with the form. Wrap a standard <select> in the same nds-form-container nds-select shell only when the design calls for the native mobile picker, as shown in the Native Select demo. With data-required on the container, form validation reads the hidden value input at submit, the same as any other field.
• Do not use form inputs for binary choices or toggles. Use switches for instant on/off toggles, checkboxes for multiple selections, or radio buttons for single selection from a set.
• Do not use plain text inputs for specialized data types. Use date picker for dates, OTP input for verification codes, and autocomplete for search-as-you-type with remote data.
• Choose nds-lg (default) for standalone forms and primary data entry. Use nds-md for compact layouts like table filters, inline editing, or sidebars where space is limited.
• Add data-required to the container rather than required on the input. The system syncs the two automatically and adds the required indicator to the label.
• Use permanent feedback (data-permanent) for format hints and character requirements. These persist across validation cycles: they hide when an error appears and restore when the error clears.
• Use prefix and suffix slots for units, currency symbols, or action buttons that contextualize the input. Prefix/suffix buttons support both subtle and solid styles, and can include icons or dropmenus for compound inputs.
• For compound inputs (phone + country code, amount + currency, measurement + unit), use a prefix-slot dropmenu with data-select-name. The dropmenu renders a hidden input that submits with the form and keeps the trigger label compact while the dropdown rows stay descriptive. See the Phone Number with Country Code demo for the full pattern.
• Validation feedback needs no markup of its own: setStatus and submit validation create the message element and place it in the field's container. Add a data-feedback-target element only when the design wants a permanent feedback position — see the Permanent Feedback section.
• Set data-error-message on the container to override default browser validation messages with context-specific text that guides the user toward correction.

Modifier Classes

Validation Attributes

Validation runs on the browser's own constraint API. These are standard HTML attributes, not NDS ones, and they go on the <input>. NDS supplies the message text in Arabic and English and places it in the field footer.

Any other failure reads Invalid input. A field that a component validates itself, such as a date picker, carries that component's own message instead.

Data Attributes

CSS Custom Properties

JavaScript API

The NDS.Forms API manages initialization, status feedback, state management, and form validation. For dynamically added form elements, call NDS.Forms.initializeContainer(element) to initialize new inputs.