Forms - National Design System

Text, number, search, email, password, textarea, and select inputs with validation, status feedback, and interactive controls

Text Input

Standard single-line text field with clear button and validation feedback

Prefix & Suffix

Text input with inline prefix and suffix labels inside the form control

Prefix
Suffix

Phone Number with Country Code

Compound input using a prefix-slot dropmenu as a value picker. The dropmenu's data-select-name opt-in captures the selected country code into a hidden input that ships with the form, and updates the trigger label to a compact display variant. Add nds-phone to the input itself to strip non-digits and any leading zero as the user types, since the country code is already prepended via the prefix slot.

Number Input

Numeric field with increment and decrement buttons for precise value adjustments

Search Input

Search field with leading icon, voice input, and clear button

Email Input

Email field with leading icon and built-in format validation

Password Input

Password field with visibility toggle and Arabic character filtering

Textarea

Multi-line text entry for longer content like messages and descriptions

Select Dropdown

Custom dropdown select with keyboard navigation and hidden input for form submission

Form Status API

Set error, success, warning, or info status on any form container with automatic feedback display

Permanent Feedback

Tips and hints that persist across validation cycles, hidden during errors and restored when cleared

Use 3-20 characters, letters and numbers only

Built-in Features

What you get out of the box with zero configuration

Auto-initialization

All form inputs auto-initialize on page load. Two-way state binding syncs disabled and data-required between inputs and containers. For dynamic content, call NDS.Forms.init().

Validation

Uses HTML5 validity checks but replaces browser popups with styled inline feedback. Error messages auto-clear on blur or change once the field is corrected. Custom messages via data-error-message.

Status Feedback

Four status types: error, success, warning, info. Feedback messages render into data-feedback-target elements. Permanent hints survive validation cycles with data-permanent.

Interactive States

Focus, active, typing, filled, and disabled states are tracked automatically via data-state. Clear buttons auto-show when the input has a value and hide when empty.

Password Toggle

Add a button with nds-toggle-password class to toggle between password and text input. The icon updates automatically to show the current visibility state.

Voice Input

Add a button with nds-voice-input class to enable speech-to-text on any input. Uses the Web Speech API with automatic language detection from the page.

Arabic Character Filtering

Password fields automatically strip Arabic and RTL characters on input, ensuring passwords contain only compatible characters without manual validation logic.

Number Input Controls

Add nds-number-increment and nds-number-decrement buttons as prefix/suffix actions. Supports min, max, and step attributes, with accelerated stepping on long press.

Usage Guidelines

When and how to use form inputs effectively

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.
  • 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.
  • Use the custom select dropdown (nds-select) when you need styled option lists that match the design system. For native mobile select behavior, use a standard <select> element instead.
  • 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.
  • Always include a data-feedback-target element in the form footer, even if initially hidden. The validation system needs this target to inject error, success, and warning messages.
  • 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

ClassDescription
nds-mdMedium size with reduced height (32px) and smaller font
nds-phoneSet on a tel input that sits next to a country-code prefix slot. On every keystroke, strips non-digit characters and any leading zero so the value submitted is the local number ready to concatenate with the prefix. Length is still controlled by the input's maxlength.

Data Attributes

AttributeDescription
data-requiredSet on nds-form-container to mark the field as required. Automatically syncs to the input's required attribute and adds the asterisk indicator.
data-error-messageSet on nds-form-container to override the default browser validation message with custom text.
data-permanentSet on a feedback element inside the footer. Permanent feedback hides during validation errors and restores when cleared.
minSet on number inputs to define the minimum allowed value (default: 0).
maxSet on number inputs to define the maximum allowed value (default: 1000).
stepSet on number inputs to define the increment/decrement size (default: 1). Long press accelerates to 10x this value.
data-select-nameSet on an nds-dropmenu (including prefix/suffix dropmenus) to turn it into a value picker. Renders a hidden <input> with this name; item clicks write the item's data-value into it and update the trigger label.
data-select-valueSet on a select-mode dropmenu to pre-select the item whose data-value matches. Takes precedence over any pre-rendered data-state="selected" item.
data-required (on dropmenu)Set on a select-mode dropmenu to add required to the hidden input, so native form submission blocks when nothing is picked.
data-trigger-labelSet on an nds-dropmenu-item to override the trigger label text when that item is chosen. Useful when the dropdown row is descriptive (Saudi Arabia (+966)) but the trigger slot needs something compact (+966).

CSS Custom Properties

PropertyDefaultDescription
--form-width100%Controls the width of the form container
--input-size40pxHeight of the input field (32px for nds-md)
--input-radiusvar(--radius-sm)Border radius of the input field

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.

// ── Initialization ────────────────────────────────── // All forms auto-initialize on page load NDS.Forms.init(); // Initialize a specific container (for dynamic content) NDS.Forms.initializeContainer(containerElement); // Initialize a dynamic <form> element (attaches submit validation) NDS.Forms.initForm(formElement); // ── Status API ────────────────────────────────────── // Set validation status with feedback message NDS.Forms.setStatus({ element: el, status: 'error', message: 'Required field' }); NDS.Forms.setStatus({ element: el, status: 'success', message: 'Looks good!' }); NDS.Forms.setStatus({ element: el, status: 'warning', message: 'Please review' }); NDS.Forms.setStatus({ element: el, status: 'info', message: 'Hint text' }); // Permanent feedback (survives validation cycles) NDS.Forms.setStatus({ element: el, status: 'neutral', message: 'Tip text', permanent: true }); // Clear status (restores permanent feedback if present) NDS.Forms.clearStatus(el); // Get current status NDS.Forms.getStatus(el); // Returns: { status: 'error', message: '...', isValid: false } // ── State Management ──────────────────────────────── // Set disabled or required state programmatically NDS.Forms.setState(el, 'disabled', true); NDS.Forms.setState(el, 'required', true); // ── Form Validation ───────────────────────────────── // Validate entire form (returns { valid, invalidFields, errors }) NDS.Forms.validateForm(formElement); // Validate specific groups (used on checkbox, radio, OTP pages) NDS.Forms.validateCheckboxGroup(group); NDS.Forms.validateRadioGroup(group); NDS.Forms.validateOtpGroup(group); // ── Events ────────────────────────────────────────── // Status change on any .nds-form-container element.addEventListener('nds:statusChange', function(e) { // e.detail: { status: 'error'|'success'|...|null, message: '...'|null } }); // Form validation events on .nds-form elements form.addEventListener('nds:formValidate', function(e) { // Fires after validation runs // e.detail: { valid: true|false, invalidFields: [...], errors: [...] } }); form.addEventListener('nds:formValid', function(e) { // Fires when form passes validation on submit }); form.addEventListener('nds:formInvalid', function(e) { // Fires when form fails validation on submit // e.detail: { invalidFields: [...], errors: [...] } }); // Select dropdown change event on .nds-form-control formControl.addEventListener('selectChange', function(e) { // e.detail: { value: 'option1', text: 'Option 1' } }); // ── Dropmenu select-mode (prefix/suffix pickers) ──── // Any .nds-dropmenu with data-select-name captures the picked value into // a hidden input and fires these two events. dropmenu.addEventListener('nds:dropmenu:selected', function(e) { // e.detail: { dropmenu, item, value } }); // Hidden input change — use this if you only care about the new value hiddenInput.addEventListener('change', function(e) { // e.target.value holds the selected data-value });
Was this page useful?
60% of users said Yes from 2843 Feedbacks