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. Usedense
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 thestep
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 | |||
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 | ||
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 | ||
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 | |||
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 | ||
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) |