Usage
Input is for short, single-line text entry. As well as plain text, it supports various types of input, including passwords and numbers. For longer, multi-line input use a Textarea, and for choosing from a set of options use a Select.
The input works two ways. Used on its own, it renders its built-in label, hint and error. Wrapped in a Field, the Field takes over: a Field Label, Field Description and Field Error provide the labelling and the input's own built-in versions step aside automatically. Use whichever fits — the Field is an opt-in, flexible alternative, not a requirement.
import "@nordhealth/components/lib/Input"
import "@nordhealth/components/lib/Field"
import "@nordhealth/components/lib/FieldLabel"
import "@nordhealth/components/lib/FieldDescription"
Standalone or inside a Field
Use the control on its own with its built-in label, hint and error, or wrap it in a Field — the Field then provides the labelling. Both render the same control:
Examples
Sizes
Use the size attribute to render a small, medium (default) or large input.
Placeholder
Use placeholder to show example or hint text before the user types. It is not a replacement for a Field Label.
Error
Show validation with the built-in error attribute, or — inside a Field — with a Field Error and the Field's invalid flag, which the input picks up automatically.
Disabled and read-only
A disabled input cannot be focused or edited and is excluded from form submission. A readonly input can be focused but not edited, and its value is still submitted.
Expand
Use expand to make the input fill the width of its container.
Date New since Jul 6, 2026
Set type="date" for a date field with the browser's native date picker. For a richer, consistent calendar experience, prefer the Date Picker component.
Time New since Jul 6, 2026
Set type="time" for a time field with the browser's native time picker, or type="datetime-local" to capture a date and time together. For a styled dropdown of selectable times, prefer the Time Picker component.
File New since Jul 6, 2026
Set type="file" to choose a file. The native "Choose file" control is styled to match other inputs; read the selected files from the underlying <input>'s files property.
Inline
Place an Input and a Button on one line to build a search or subscribe row.
Grid
Use a grid layout on a Field Group to place multiple inputs side by side.
Badge
Add a Badge to a Field Label to highlight a field, such as a beta or recommended one.
Form
Compose Input with the Field family inside a <form> to build a complete, labelled form with helper text, a Select, and actions.
Hint
Add a Field Hint to give the user extra guidance about what to enter.
Required
Set required on the Field Label to mark the field as mandatory and show the required indicator.
Hidden label
Use a visually hidden label when the context already makes the input's purpose clear. The label stays available to assistive technology.
Prefix or suffix
Use the start and end slots to show a unit, currency symbol, or other adornment alongside the value.
Units
Pair an Input with a Select to let the user choose a unit for the entered value.
Numeric input
For numeric entry — with stepper controls, min/max, formatting and locale — use the dedicated Number Field rather than an Input with type="number".
Search
Set type="search" to render a search input with a clear button.
Autocomplete
Use the autocomplete attribute to hint at the type of value expected so browsers can offer suggestions.
Input mask
Use an input mask to format the value as the user types, such as a phone number or date.
Input mode
Use inputmode to hint at the on-screen keyboard layout mobile browsers should display.
Disallow pattern
Use a disallow pattern to block characters that should never be entered.
Text selection
Programmatically select text within the input using the selection APIs.
Custom width
Constrain the input to a fixed width using a CSS custom property.
Custom button
Place a Button in the end slot to add an inline action to the input.
Custom icon
Add an Icon to the start slot to indicate the input's purpose.
RTL
Input follows the document or container direction. Toggle the direction to see the layout mirror.
Accessibility
- Always give the input an accessible name, either with the built-in
labelor, inside a Field, a Field Label connected viafor. - Convey validation with the built-in
erroror a Field Error rather than colour alone — it is associated with the input and announced to assistive technology. - Mark required fields by setting
requiredon the input. Inside a Field, the Field Label shows the required indicator automatically. - Prefer
readonlyoverdisabledwhen the value is still relevant but not editable, as disabled inputs are removed from the tab order and not submitted with the form. - Choose an appropriate
type(such asemail,passwordorsearch) so browsers and assistive technology present the correct keyboard and behaviour.
API reference
Input
Inputs are used to allow users to provide text input when the expected input is short. As well as plain text, Input supports various types of text, including passwords and numbers.
<nord-input></nord-input>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
type | type | The type of the input. | | 'text'
| 'email'
| 'password'
| 'tel'
| 'url'
| 'search'
| 'number'
| 'date'
| 'time'
| 'datetime-local'
| 'file'
| 'unit'
| 'button' | 'text' |
expand | expand | Controls whether the input expands to fill the width of its container. | boolean | false |
disallowPattern | disallow-pattern | Optionally disallow certain characters from being used inside the input, using a regex pattern. | string | undefined | undefined |
inputmode | inputmode | The inputmode attribute provides a hint to the browser about what type of keyboard to open on mobile devices. Valid values: none, text, decimal, numeric, tel, search, email, url When not explicitly set, defaults based on input type: - type="number" → inputmode="numeric" - type="email" → inputmode="email" - type="tel" → inputmode="tel" - type="url" → inputmode="url" - type="search" → inputmode="search" Can be explicitly overridden for any type. | 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url' | undefined | undefined |
size | size | The size of the component. | 's' | 'm' | 'l' | 'm' |
placeholder | placeholder | Placeholder text to display within the control. | string | undefined | — |
required | required | Determines whether the control is required or not.
A required control is announced as such to assistive technology and, inside
a <nord-field>, drives the required indicator on the <nord-field-label>.
When using this property you need to also set “novalidate” attribute on a form element to prevent browser from displaying its own validation errors. | boolean | false |
autocomplete | autocomplete | Specifies the data type of the field, so that the browser may attempt to fill out the field automatically on behalf of the user. | AutocompleteAttribute | 'off' |
readonly | readonly | Makes the component readonly, so that it is not editable. Readonly differs from disabled in that readonly fields are still focusable and will be submitted with a form. | boolean | false |
disabled | disabled | Makes the component disabled. This prevents users from being able to interact with the component, and conveys its inactive state to assistive technologies. | boolean | false |
name | name | The name of the form component. | string | undefined | — |
value | value | The value of the form component. | string | '' |
form | form | Gets the form, if any, associated with the form element. The setter accepts a string, which is the id of the form. | HTMLFormElement | null | — |
Field properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
label | label | Label for the control. Ignored when the control is wrapped in a
<nord-field>, which provides the label via <nord-field-label>. | string | '' |
hint | hint | Optional hint text shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-description>. | string | undefined | — |
hintBelow | hint-below | Renders the hint below the control and any error instead of below the label. | boolean | false |
hideLabel | hide-label | Visually hide the label, but still expose it to assistive technologies. | boolean | false |
error | error | Optional error shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-error>. | string | undefined | — |
hideRequired | hide-required | Visually hide the required indicator, but still expose the required state to assistive technologies. | boolean | false |
Slots
| Slot name | Description |
|---|---|
label | Use when a label requires more than plain text. |
hint | Optional slot that holds hint text for the input. |
error | Optional slot that holds error text for the input. |
start | Optional slot used to place an icon or prefix at the start of the input. |
end | Optional slot used to place an icon or suffix at the end of the input. |
Methods
| Method name | Parameters | Description |
|---|---|---|
focus(options?: FocusOptions) => void | options: An object which controls aspects of the focusing process. | Programmatically move focus to the component. |
blur() => void | N/A | Programmatically remove focus from the component. |
click() => void | N/A | Programmatically simulates a click on the component. |
| Event | Detail Type | Description |
|---|---|---|
select | NordEvent | Fired when some text has been selected. |
input | NordEvent | Fired as the user types into the input. |
change | NordEvent | Fired whenever the input's value is changed via user interaction. |
CSS Properties
CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.
| Property | Description | Default |
|---|---|---|
--n-input-inline-size | Controls the inline size, or width, of the input. | 240px |
--n-input-block-size | Controls the block size, or height, of the input using our spacing tokens. | var(--n-space-xl) |
--n-input-background | Controls the background of the input, using our color tokens. | var(--n-color-surface) |
--n-input-color | Controls the text color of the input, using our color tokens. | var(--n-color-text) |
--n-input-border-color | Controls the border color of the input, using our color tokens. | var(--n-color-border-strong) |
--n-input-border-radius | Controls how rounded the corners are, using border radius tokens. | var(--n-border-radius-s) |
--n-input-text-align | Controls the alignment of text within the input itself. | start |
--n-label-color | Controls the text color of the label, using our color tokens. | var(--n-color-text) |
Dependencies
This component is internally dependent on the following components:
Design guidelinesFor designers
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Use to provide a text input where the expected input is short.
- Use to only ask for information that’s really needed. Hide optional fields by default if possible or have them shown with a lower priority.
- Use help text and placeholder to provide additional, non-critical instructions.
- Validate input as soon as users have finished interacting with them (but not before).
- Where necessary, label the input as “Optional” when you need to request input that’s not required.
Don’t
- Don’t use when the expected text input is long. Use textarea component instead.
- Don’t use the placeholder to provide information that’s required to use the input. Hint text should be used for this purpose instead.
Hint placement
Hint text is rendered above the control by default to preserve existing behavior for current consumers. Use the hint-below property to opt in to rendering the hint below the control and any error.
This is a non-breaking rollout for teams adopting the new layout gradually. Existing integrations keep the current placement unless hint-below is explicitly set.
Content guidelines
Input labels act as a title for the text field. Labels should typically be short and in noun form:
When writing input labels, always write them in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):
When an input isn’t part of a form and is placed individually on a page, you could provide the input label as a call to action:
Do not use colons in input label:
Types
This section describes the different input types, their purpose, and when to use each type.
| Name | Purpose |
|---|---|
text | The default and most common variant. Displayed as a single-line text field. Line-breaks are automatically removed from the input value. |
email | A field for editing an email address. Looks similar to a text input, but has validation parameters and relevant keyboard for devices with dynamic keyboards. |
password | A single-line text field where the value is obscured. This type will alert user if a site is not secure. |
tel | A field for entering a telephone number. Displays a number keypad on mobile devices. |
url | A field variant that is used to let the user enter and edit an URL. |
search | A single-line text field for entering search strings. |
number | Used to let the user enter a number. |
Icon usage in input
Each input size has a recommended icon size. The medium input uses the s icon size, the small input uses the xs icon size, and the large input uses the m icon size. The icon will adjust size automatically based on the button size, so you will get the correct behavior by default. However, this can be overridden by explicitly setting a size on the icon.
Input mode
The inputmode attribute provides a hint to the browser about what type of keyboard to show on mobile devices. This is particularly useful for optimizing the mobile experience by opening the appropriate keyboard (numeric, email, URL, etc.) based on the expected input.
- The
inputmodeattribute accepts the following values:none,text,decimal,numeric,tel,search,email, andurl. - The component automatically defaults
inputmodebased on the inputtype:type="number"→inputmode="numeric"type="email"→inputmode="email"type="tel"→inputmode="tel"type="url"→inputmode="url"type="search"→inputmode="search"
- You can override these defaults by explicitly setting a custom
inputmodevalue, for exampleinputmode="decimal"on a number type input, orinputmode="numeric"on a text type input.
Input masking
We recommend using Maskito for creating an input mask which ensures that users type values according to a predefined format.