Skip to main content

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

VariantUsage
inputA couple of words, sentence, or number.
textareaSeveral 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

NameTypeDefaultRequiredDescription
autoCompletestringThe native autocomplete attribute
classNamestring
dataTeststring'dhis2-uicore-input'
densebooleanMakes the input smaller
disabledbooleanDisables the input
errorcustomApplies 'error' appearance for validation feedback. Mutually exclusive with valid and warning props
initialFocusbooleanThe input grabs initial focus on the page
loadingbooleanAdds a loading indicator beside the input
maxstringThe native max attribute, for use when type is 'number'
minstringThe native min attribute, for use when type is 'number'
namestringName associated with the input. Passed to event handler callbacks in object
placeholderstringPlaceholder text for the input
readOnlybooleanMakes the input read-only
rolestringSets a role attribute on the input
stepstringThe native step attribute, for use when type is 'number'
tabIndexstring
typeinputTypes'text'The native input type attribute
validcustomApplies 'valid' appearance for validation feedback. Mutually exclusive with error and warning props
valuestringValue in the input. Can be used to control the component (recommended). Passed to event handler callbacks in object
warningcustomApplies 'warning' appearance for validation feedback. Mutually exclusive with valid and error props
onBlurfunctionCalled with signature ({ name: string, value: string }, event)
onChangefunctionCalled with signature ({ name: string, value: string }, event)
onFocusfunctionCalled with signature ({ name: string, value: string }, event)
onKeyDownfunctionCalled 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

NameTypeDefaultRequiredDescription
autoCompletestringThe native autocomplete attribute
classNamestring
dataTeststring'dhis2-uiwidgets-inputfield'
densebooleanMakes the input smaller
disabledbooleanDisables the input
errorcustomApplies 'error' appearance for validation feedback. Mutually exclusive with valid and warning props
helpTextstringGuiding text for how to use this input
initialFocusbooleanThe input grabs initial focus on the page
inputWidthstringDefines the width of the input. Can be any valid CSS measurement
labelstringLabel text for the input
loadingbooleanAdds a loading indicator beside the input
maxstringThe native max attribute, for use when type is 'number'
minstringThe native min attribute, for use when type is 'number'
namestringName associated with the input. Passed to event handler callbacks in object
placeholderstringPlaceholder text for the input
readOnlybooleanMakes the input read-only
requiredbooleanIndicates this input is required
stepstringThe native step attribute, for use when type is 'number'
tabIndexstring
typeinputTypesType of input
validcustomApplies 'valid' appearance for validation feedback. Mutually exclusive with error and warning props
validationTextstringText below input for validation feedback. Receives styles depending on validation status
valuestringValue in the input. Can be used to control the component (recommended). Passed to event handler callbacks in object
warningcustomApplies 'warning' appearance for validation feedback. Mutually exclusive with valid and error props
onBlurfunctionCalled with signature ({ name: string, value: string }, event)
onChangefunctionCalled with signature ({ name: string, value: string }, event)
onFocusfunctionCalled with signature ({ name: string, value: string }, event)
onKeyDownfunctionCalled with signature ({ name: string, value: string }, event)