Text field
A text field can be used for the user to input and edit data.
Examples
Usage
Do
- Use to accept data input
- Use single-line text field for data that isn’t longer than a single line
- Use the inline text field type for compact UIs like inline search and quick filtering
- Use a label when possible for standard text fields
- End labels with a colon (e.g. “Full name:”)
- Use placeholders only for secondary information, as the text disappears on focus
- Write labels and placeholders in sentence case
- Keep help text succinct, ideally no longer than a single line
Don’t
- Reduce or increase the proportions
- Use when there is a small, defined set of options the user can choose from
- Use just to display copy
- Use a disabled text field to display view-only copy
- Use inline with body text
- Add a label to inline text fields
- Use a multi-line text box when users only need a single line
- Use placeholder text to pre-populate the text box
- Use an inline text field when an error state is needed
Anatomy
- (1) Standard text field
- (2) Inline text field
- (3) Text field with icon
- (4) Text field with placeholder
- (5) Text field with label
- (6) Text field with helper text
- (7) Disabled text field
Default sizes
- (1) Single-line default text field has a default width of 296px
- (2) The full-width property for single and multi-line text fields makes them take up the entire available space within the parent container
- (3) The recommended minimum width for a single-line text field is 64px
Auto-width single-line text field
Auto-width fields will grow until they reach the maximum space available in its container.
Multi-line text field
- (1) The default height of a multi-line text field is 4 lines
- (2) The default height of an auto-height multi-line text field is 2 lines
Text field labels, help and error text
- (1) Standard text field with label
- (2) Optional text field indicator
- (3) Text field with help text
- (4) Text field with error message and indicator — the error message replaces the help text
Vertical spacing
- (1) Between label and text field, and text field and help text: 8px
- (2) Between text field and next label, and help text and next label: 24px
Related
APIs
TextFieldStyle
normal0
number
Rendered closer to a typical <input />
inline1
number
Rendered with no border and a non-white background
TextFieldFocusTreatmentBehavior
all0
number
Focus treatment will appear when the TextField has focus via mouse or keyboard
keyboardOnly1
number
Focus treatment will only appear when the TextField has focus via keyboard
none2
number
Focus treatment will never appear (used within FilterBar)
TextFieldWidth
auto"auto"
string
No width property is added to the TextField, it will grow to fill its container.
standard"bolt-textfield-default-width"
string
A standard width of 296px is set for the TextField
tabBar"bolt-textfield-inline-tabbar-width"
string
Width for the TextField when it is used inline within a TabBar
ITextField
focus
(): void
Sets focus on the TextField if it's currently mounted
readonly selectionEnd
number | null
Gets the end position or offset of a text selection.
readonly selectionStart
number | null
Gets the starting position or offset of a text selection.
select
(): void
Selects content in the text field.
setSelectionRange
(start: number, end: number, direction?: "forward" | "backward" | "none" | undefined): void
Sets the currently selected values in the TextField if it's currently mounted
ITextFieldProps
activatablefalse
boolean
Whether or not the input can be activated. Text will not be selectable and a cursor: pointer
will be used.
ariaActiveDescendant
string
aria-activedescendant on the input/textfield.
ariaAutoComplete
"none" | "list" | "inline" | "both"
aria-autocomplete on the input/textfield.
ariaControls
string
aria-controls on the input/textfield.
ariaDescribedBy
string
aria-describedby on the input/textfield.
ariaExpanded
boolean
aria-expanded on the input/textfield.
ariaHasPopup
boolean | "menu" | "listbox" | "tree" | "grid" | "dialog"
aria-hasPopup on the input/textfield.
ariaInvalid
boolean
aria-invalid on the input/textfield.
ariaLabel
string
aria-label on the input/textfield.
ariaLabelledBy
string
aria-labelledby on the input/textfield.
ariaRoleDescription
string
aria-roledescription on the input/textfield.
autoAdjustHeightfalse.
boolean
Adjust the textfield height as the contents change.
autoCompletefalse.
boolean
Should the input tag have autocomplete enabled. Ignored if multiline is set to true.
autoFocus
boolean
autoFocus on the input/textfield.
autoSelect
boolean
Supply autoSelect to select all the text in the input when the textfield gets
focus. This is useful if you want the user to copy the text, or replace the text
upon typing instead of changing the current value.
className
string
Classname passed to the TextField.
containerClassName
string
ClassName to pass to the element containing the TextField and description.
disabled
boolean
Indicates that the element is disabled - influences styling,
aria-disabled, and disabled on the input/textarea.
excludeFocusZone
boolean
Set to true if you don't want focus managed by a FocusZone.
excludeTabStop
boolean
Set to true if you don't want the textfield to be tabbable.
focusTreatmentTextFieldFocusTreatmentBehavior.all
Indicates how we should apply the focus treatment to the
TextField. Default is to show the focus treatment when focused via keyboard or mouse.
TextFields that do not wish to have focus treatment (e.g. in the filter bar) should use "none"
inputClassName
string
Classname passed to the input/textarea element.
inputElement
React.RefObject<HTMLTextAreaElement & HTMLInputElement>
ref to get passed to the input element.
inputId
string
Id to pass to the input element.
inputTypetext
"password" | "text" | "button" | "number"
Type that is passed to the <input> element, e.g. password, number, etc.
See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types for a full list
label
React.ReactNode
Label to be rendered before the TextField. Will be wrapped in a
<label> element and wired up with the appropriate aria attributes.
maxLength
number
MaxLength on the input/textarea.
maxWidth
number
The maximum width in px that the textfield will grow to.
multiline
boolean
If true, uses a textarea instead of an input element.
onBlur
() => void
Called when blur event is fired by the input/textarea.
onChange
(event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>, value: string) => void
Called when the value of the input/textarea changes.
onClick
(event: React.MouseEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the element is clicked.
onFocus
(event: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the focus event is fired by the input/textarea.
onKeyDown
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key down event is fired by the input/textarea.
onKeyPress
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key press event is fired by the input/textarea.
onKeyUp
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key press event is fired by the input/textarea.
onPaste
(event: React.ClipboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the paste event is fired by the input/textarea.
placeholder
string
Placeholder on the input/textarea.
readOnlyfalse
boolean
If the TextField should be read-only.
requiredfalse
boolean
When true, the input element will be marked as required and an asterisk will be appended to the label.
resizabletrue if the TextField is multiline.
boolean
If the text area should be resizable. Only used if multiline is true.
role
string
role to use in the TextField.
rows
number
Number of rows the text area should have. Only used if multiline is set to true.
showCharacterCounter
boolean
If the character counter against the limit in the lower right corner should be displayed.
Only used if maxLength is provided.
spellCheckundefined which will default to the browser's default for the input and textarea tags.
boolean
When true or false, overrides the default spellCheck behavior of the browser.
styleTextFieldStyle.normal
Changes visual appearance of TextField. Use TextFieldStyle.inline to style as an inline text field.
tabIndex
number
Sets the tabindex on the input/textarea element.
value
IReadonlyObservableValue<string | undefined> | string
Text value of the input/textarea. This prop is 100% controlled
by the consumer. onChange must also be implemented in order to
work properly. If this value is a raw string, the prop must be
updated to cause the TextField to re-render. If this value is an
ObservableValue, then changing its value will cause the TextField
to re-render.
ITextFieldWithMessageProps
className
string
Classname passed to the root element of the component
error
IReadonlyObservableValue<boolean> | boolean
Whether or not the message is considered an error message - will add
appropriate classNames to TextField, message, as well as aria properties.
message
IReadonlyObservableValue<string> | string
An optional message to display with the textfield
messageClassName
string
Classname passed to the element containing the message