Input

An input is used to enter data, like text or a number.

Demo

Usage

When to use

• Entering or editing data. Inputs are used to add or change data, like text or a number.

When not to use

• Choosing from options. Don't use an input to choose from other a list of options, use a Select instead.

Variants

Variant	Usage
input	A couple of words, sentence, or number.
textarea	Several sentences

Format

Content

Label

Demo

<InputField value="Malaria Registration" label="Program name" />

• Use a label above the input to show what the input is for.

Placeholder

Demo

<InputField placeholder="Type your program name here" label="Program name" />

• Only use placeholder text to clarify what kind of content is expected.
• Placeholder text shouldn't repeat the label.
• Always use placeholder text if a label isn't used.
• Placeholder text disappears when entering content, so make sure it's not critical.

Help text

Demo

<InputField
    placeholder="Enter program name"
    label="Program name"
    helpText="Used for data entry and shown on all reports"
/>

• Use help text to tell the user about any limitations or expectations for the content.
• Help text can also be used to clarify what the input is for if it's a complex concept.

Size

Demo

<InputField value="Malaria Registration" label="Program name" dense />

• Inputs are available in two sizes, regular and dense. Regular sized inputs are useful when there's space available. Use dense sized inputs in compact, information-dense interfaces.

Width

Demo

<InputField inputWidth="100px" />
<InputField inputWidth="220px" />

Inputs width should reflect the expected content.

• If a three digit number is expected then the input should be narrow.
• If a longer sentence is expected then the input should be wider.

Options

Textarea

Demo

<TextAreaField label="Description of symptoms" />

• Use a Textarea if more than a single sentence of content is expected.
• Textarea is available as a standalone component.

Validation

• Validating the type of data entered isn't part of the components themselves.
• Read more about form handling in DHIS2.

Read-only

Demo

<InputField value="OU897234798" label="Unique ID" readOnly />

• Use a read-only input if it makes sense to show the input, but the content can't be changed.
• Read-only inputs are useful to show that a value is locked, like a unique ID.
• Offer help text for read-only inputs if it's unclear why the content can't be changed.

State: Error

Demo

<InputField
    value="Malaria Registration"
    label="Program name"
    error
    validationText="This program name is already in use"
/>

• Use an error state if there's a problem with the content of the input, or if it's required but empty.
• Don't show an error too early, give the user a chance to finish entering data.
• The error text should help the user fix the problem. Refer to the error writing guidelines for examples.

State: Disabled

Demo

<InputField value="Referrals" label="Stage name" readOnly />

However, it is recommended to add a Tooltip to explain why the input is disabled.

<Tooltip content="Stage name is automatically generated and can't be changed.">
    <InputField value="Referrals" label="Stage name" readOnly />
</Tooltip>

• Use a disabled state if the input temporarily can't be used.
• Show a Tooltip on hover or focus to explain why the input is disabled.

Data type: Text

Demo

<InputField value="Olukayode" label="First name" inputWidth="240px" />

• Text inputs are the default type.
• Use a text input for entering any kind of text content, like a mix of letters and numbers.

Data type: Number

Demo

<InputField
    value="19"
    label="Admission count"
    inputWidth="100px"
    type="number"
/>

• Use a number input for entering numbers.
• The step value should reflect the expected content. If entering a number that's always a multiple of 10, use 10 as the step value.

Data type: Password

Demo

<InputField
    value="It's a secret!"
    label="Password"
    inputWidth="320px"
    type="password"
/>

• Use a password input whenever a user is entering a password or secret value.

Data type: Date / time

Demo

<InputField
    label="Incident date and time"
    inputWidth="240px"
    type="datetime-local"
/>

• Using date/time inputs offers different interactions depending on the user's browser.

Other data types

The following data types don't change the interaction with the input, but should be used for clarity:

• Telephone (tel)
• Email (email)
• Month (month)
• Week (week)
• Search (search)

API Reference

Input

Usage

To use Input, you can import the component from the @dhis2/ui library

import { Input } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
autoComplete	string			The native autocomplete attribute
className	string
clearable	boolean			Makes the input field clearable
dataTest	string	'dhis2-uicore-input'
dense	boolean			Makes the input smaller
disabled	boolean			Disables the input
error	custom			Applies 'error' appearance for validation feedback. Mutually exclusive with valid and warning props
initialFocus	boolean			The input grabs initial focus on the page
loading	boolean			Adds a loading indicator beside the input
max	string			The native max attribute, for use when type is 'number'
min	string			The native min attribute, for use when type is 'number'
name	string			Name associated with the input. Passed to event handler callbacks in object
placeholder	string			Placeholder text for the input
prefixIcon	element			Add prefix icon
readOnly	boolean			Makes the input read-only
role	string			Sets a role attribute on the input
step	string			The native step attribute, for use when type is 'number'
tabIndex	string
type	inputTypes	'text'		The native input type attribute
valid	custom			Applies 'valid' appearance for validation feedback. Mutually exclusive with error and warning props
value	string			Value in the input. Can be used to control the component (recommended). Passed to event handler callbacks in object
warning	custom			Applies 'warning' appearance for validation feedback. Mutually exclusive with valid and error props
width	string			Defines the width of the input. Can be any valid CSS measurement
onBlur	function			Called with signature ({ name: string, value: string }, event)
onChange	function			Called with signature ({ name: string, value: string }, event)
onFocus	function			Called with signature ({ name: string, value: string }, event)
onKeyDown	function			Called with signature ({ name: string, value: string }, event)

InputField

Usage

To use InputField, you can import the component from the @dhis2/ui library

import { InputField } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
autoComplete	string			The native autocomplete attribute
className	string
clearable	boolean			Makes the input field clearable
dataTest	string	'dhis2-uiwidgets-inputfield'
dense	boolean			Makes the input smaller
disabled	boolean			Disables the input
error	custom			Applies 'error' appearance for validation feedback. Mutually exclusive with valid and warning props
helpText	string			Guiding text for how to use this input
initialFocus	boolean			The input grabs initial focus on the page
inputWidth	string			Defines the width of the input. Can be any valid CSS measurement
label	string			Label text for the input
loading	boolean			Adds a loading indicator beside the input
max	string			The native max attribute, for use when type is 'number'
min	string			The native min attribute, for use when type is 'number'
name	string			Name associated with the input. Passed to event handler callbacks in object
placeholder	string			Placeholder text for the input
prefixIcon	element			Add prefix icon
readOnly	boolean			Makes the input read-only
required	boolean			Indicates this input is required
step	string			The native step attribute, for use when type is 'number'
tabIndex	string
type	inputTypes			Type of input
valid	custom			Applies 'valid' appearance for validation feedback. Mutually exclusive with error and warning props
validationText	string			Text below input for validation feedback. Receives styles depending on validation status
value	string			Value in the input. Can be used to control the component (recommended). Passed to event handler callbacks in object
warning	custom			Applies 'warning' appearance for validation feedback. Mutually exclusive with valid and error props
onBlur	function			Called with signature ({ name: string, value: string }, event)
onChange	function			Called with signature ({ name: string, value: string }, event)
onFocus	function			Called with signature ({ name: string, value: string }, event)
onKeyDown	function			Called with signature ({ name: string, value: string }, event)