Marigold
Getting StartedFoundationsComponentsPatternsRecipesReleases
Discover new Tutorials!

Components

Overview

Application

MarigoldProvider
updated
RouterProvider
updated

Layout

Aside
Aspect
Breakout
Center
Columns
Container
Grid
Inline
Inset
Scrollable
Split
Stack
updated
Tiles

Form

Autocomplete
Button
updated
Calendar
Checkbox
ComboBox
DateField
DatePicker
Form
Multiselect
new
NumberField
Radio
SearchField
Select
Slider
Switch
TextArea
TextField
TimeField
new

Collection

SelectList
updated
Table
updated
Tag

Navigation

Accordion
Breadcrumbs
beta
Pagination
Tabs

Overlay

ContextualHelp
new
Dialog
Menu
Toast
beta
Tooltip
updated

Content

Badge
Body
Card
Divider
updated
Footer
Header
Headline
updated
Icon
updated
Image
Link
updated
List
updated
SectionMessage
SVG
updated
Text
updated
VisuallyHidden
updated
XLoader

Formatters

DateFormat
NumericFormat

Hooks and Utils

cn
cva
extendTheme
useAsyncListData
useListData
useResponsiveValue
useTheme

TextField

Component for input forms.

The <TextField> is a form component which allows user to enter text with a keyboard. It creates interactive controls for web-based forms in order to accept data from the user. It is also one of the most powerful and complex elements in all of HTML due to the sheer number of combinations of input types and attributes.

Anatomy

Text fields consist of an input element, which is a container in which the user enters data, and a label which informs the user about the content they need to enter in the field. <TextField> automatically manages the relationship between these two elements. It also supports optional description and error message elements, which can be used to provide more context about the field, and any validation messages.

Anatomy of table

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Variant
Size
The selected theme does not has any options for "variant" and "size".

Usage

Use a <TextField> if a user needs to input unique information that cannot be predicted with a preset of options (e.g. Radio, Select etc.) and also a user needs to input memorable data that can be entered more quickly in a free-hand format versus a more complex control.

Avoid using <TextField> if a user can only enter an option from a predefined list then avoid using a free-form text input as it is likely to result in an error. Consider using a selection control such as a dropdown, select, or radio button group instead.

Label

In general label should be short and precise about what is expected from the user. Avoid unnecessary instructional verbs (doing words) in your labels and hints because it’s already implied by the input field. Avoid placeholder text in most cases, as there’s no need for it (more about it in the next section).

Do
Do: Use short labels
Use short labels.
Don't
Don’t use unnecessary instructional verbs

Don’t use unnecessary instructional verbs.

Placeholder

Placeholder text is a short hint displayed inside an input field before a user enters a value. To save space, placeholder text is often used instead of a label, as shown in the first example. This is problematic for the following reasons:

  • Placeholder text disappears once a person starts filling in an input field, causing some to forget what the field was for
  • Some might miss or skip fields with placeholder text, as it can look like the field has already been pre-filled.
  • Placeholder text colour contrast is almost always inaccessible, as it’s very light by design. This means many will struggle to read the label.
Do
Do: Use label instead of a placeholder
Use label instead of a placeholder.
Don't
Don’t use placeholder text instead of a label

Don’t use placeholder text instead of a label.

Additional description

Sometimes the label isn't enough for the user. In this case, to gather additional support for the user we can use the help text. With this we can add helpful hints for the user below the input field. Beside that the help text is placed in close proximity to the associated input field.

Do
Do: Use help text to show an example what's expected

Use help text to show an example what's expected.

Do
Do: Explain why certain information is needed
Explain why certain information is needed.

Textfield with an error

Error messages should let people know that a problem occurred, why it happened, and provide a solution to fix it and move forward.

Don't
Don't: Never blame the user

Never blame the user. Always be positive and helpful.

Don't
Don't: Be concise and avoid unnecessary words

Be concise and avoid unnecessary words like “please”, “sorry” and “oops”

Do
Do: Use detailed messages instead of global messages

Use detailed messages instead of global messages.

The error prop toggles the error state of a field. The errorMessage prop can then be used to provide feedback to the user about the error. The message disappears automatically when all requirements are met.

Preview
Code
Enter your 5 digit zip code.
Note

Press Enter, after typing your text, to trigger the validation.

Props

Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
View TextField stories
aria-activedescendant?
string;
Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
aria-autocomplete?
"none" | "inline" | "list" | "both";
Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made.
aria-controls?
string;
Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-describedby?
string;
Identifies the element (or elements) that describes the object.
aria-details?
string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-errormessage?
string;
Identifies the element that provides an error message for the object.
aria-haspopup?
boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog";
Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
aria-label?
string;
Defines a string value that labels the current element.
aria-labelledby?
string;
Identifies the element (or elements) that labels the current element.
autoComplete?
string;
Describes the type of autocomplete functionality the input should provide if any. See MDN.
autoCorrect?
string;
An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See MDN.
autoFocus?
boolean;
Whether the element should receive focus on render.
defaultValue?
string;
The default value of the input field.
Defaults to:
"none"
description?
ReactNode;
A helpful text.
dir?
string;
disabled?
boolean;
If true, the input is disabled.
Defaults to:
"false"
enterKeyHint?
"enter" | "done" | "go" | "next" | "previous" | "search" | "send";
An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See MDN.
error?
boolean;
If true, the field is considered invalid and if set the errorMessage is shown instead of the description.
Defaults to:
"false"
errorMessage?
ReactNode | ((v: ValidationResult) => ReactNode);
An error message.
excludeFromTabOrder?
boolean;
Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
form?
string;
The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
hidden?
boolean;
id?
string;
The element's unique identifier. See MDN.
inert?
boolean;
inputMode?
"none" | "search" | "text" | "url" | "tel" | "email" | "numeric" | "decimal";
Hints at the type of data that might be entered by the user while editing the element or its contents. See MDN.
label?
ReactNode;
Specifies the label of the field.
lang?
string;
max?
string;
The maximum value for the input field.
Defaults to:
"none"
maxLength?
number;
The maximum number of characters supported by the input. See MDN.
min?
string;
The minimum value for the input field.
Defaults to:
"none"
minLength?
number;
The minimum number of characters required by the input. See MDN.
name?
string;
The name of the input element, used when submitting an HTML form. See MDN.
onAnimationEnd?
AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?
AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?
AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?
AnimationEventHandler<HTMLDivElement>;
onAnimationStart?
AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?
AnimationEventHandler<HTMLDivElement>;
onAuxClick?
MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?
MouseEventHandler<HTMLDivElement>;
onBeforeInput?
FormEventHandler<HTMLInputElement>;
Handler that is called when the input value is about to be modified. See MDN.
onBlur?
(e: FocusEvent<HTMLInputElement, Element>) => void;
Handler that is called when the element loses focus.
onChange?
(value: string) => void;
Handler that is called when the value changes.
onClick?
MouseEventHandler<HTMLDivElement>;
onClickCapture?
MouseEventHandler<HTMLDivElement>;
onCompositionEnd?
CompositionEventHandler<HTMLInputElement>;
Handler that is called when a text composition system completes or cancels the current text composition session. See MDN.
onCompositionStart?
CompositionEventHandler<HTMLInputElement>;
Handler that is called when a text composition system starts a new text composition session. See MDN.
onCompositionUpdate?
CompositionEventHandler<HTMLInputElement>;
Handler that is called when a new character is received in the current text composition session. See MDN.
onContextMenu?
MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?
MouseEventHandler<HTMLDivElement>;
onCopy?
ClipboardEventHandler<HTMLInputElement>;
Handler that is called when the user copies text. See MDN.
onCut?
ClipboardEventHandler<HTMLInputElement>;
Handler that is called when the user cuts text. See MDN.
onDoubleClick?
MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?
MouseEventHandler<HTMLDivElement>;
onFocus?
(e: FocusEvent<HTMLInputElement, Element>) => void;
Handler that is called when the element receives focus.
onFocusChange?
(isFocused: boolean) => void;
Handler that is called when the element's focus status changes.
onGotPointerCapture?
PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?
PointerEventHandler<HTMLDivElement>;
onInput?
FormEventHandler<HTMLInputElement>;
Handler that is called when the input value is modified. See MDN.
onKeyDown?
(e: KeyboardEvent) => void;
Handler that is called when a key is pressed.
onKeyUp?
(e: KeyboardEvent) => void;
Handler that is called when a key is released.
onLostPointerCapture?
PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?
PointerEventHandler<HTMLDivElement>;
onMouseDown?
MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?
MouseEventHandler<HTMLDivElement>;
onMouseEnter?
MouseEventHandler<HTMLDivElement>;
onMouseLeave?
MouseEventHandler<HTMLDivElement>;
onMouseMove?
MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?
MouseEventHandler<HTMLDivElement>;
onMouseOut?
MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?
MouseEventHandler<HTMLDivElement>;
onMouseOver?
MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?
MouseEventHandler<HTMLDivElement>;
onMouseUp?
MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?
MouseEventHandler<HTMLDivElement>;
onPaste?
ClipboardEventHandler<HTMLInputElement>;
Handler that is called when the user pastes text. See MDN.
onPointerCancel?
PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?
PointerEventHandler<HTMLDivElement>;
onPointerDown?
PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?
PointerEventHandler<HTMLDivElement>;
onPointerEnter?
PointerEventHandler<HTMLDivElement>;
onPointerLeave?
PointerEventHandler<HTMLDivElement>;
onPointerMove?
PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?
PointerEventHandler<HTMLDivElement>;
onPointerOut?
PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?
PointerEventHandler<HTMLDivElement>;
onPointerOver?
PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?
PointerEventHandler<HTMLDivElement>;
onPointerUp?
PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?
PointerEventHandler<HTMLDivElement>;
onScroll?
UIEventHandler<HTMLDivElement>;
onScrollCapture?
UIEventHandler<HTMLDivElement>;
onSelect?
ReactEventHandler<HTMLInputElement>;
Handler that is called when text in the input is selected. See MDN.
onTouchCancel?
TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?
TouchEventHandler<HTMLDivElement>;
onTouchEnd?
TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?
TouchEventHandler<HTMLDivElement>;
onTouchMove?
TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?
TouchEventHandler<HTMLDivElement>;
onTouchStart?
TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?
TouchEventHandler<HTMLDivElement>;
onTransitionCancel?
TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?
TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?
TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?
TransitionEventHandler<HTMLDivElement>;
onTransitionRun?
TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?
TransitionEventHandler<HTMLDivElement>;
onTransitionStart?
TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?
TransitionEventHandler<HTMLDivElement>;
onWheel?
WheelEventHandler<HTMLDivElement>;
onWheelCapture?
WheelEventHandler<HTMLDivElement>;
pattern?
string;
Regex pattern that the value of the input must match to be valid. See MDN.
placeholder?
string;
Placeholder text for the input field.
Defaults to:
"none"
readOnly?
boolean;
If true, the input is readOnly.
Defaults to:
"false"
ref?
Ref<HTMLInputElement>;
Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}
required?
boolean;
If true, the input is required.
Defaults to:
"false"
spellCheck?
string;
An enumerated attribute that defines whether the element may be checked for spelling errors. See MDN.
translate?
"yes" | "no";
type?
"search" | "text" | "url" | "tel" | "email" | "password" | (string & {});
The type of input to render. See MDN.
validate?
(value: string) => true | ValidationError | null;
A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
validationBehavior?
"native" | "aria";
Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
Defaults to:
'native'
value?
string;
The value of the input field.
Defaults to:
"none"
width?
WidthProp;
Sets the width of the field. You can see allowed tokens here: https://tailwindcss.com/docs/width
Defaults to:
"full"

Related

Building Forms
This page should introduce you on how to build forms with Marigold.
Forms
Here you can find some recipes for some form components.
Last update: a month ago
Build with 🥵, 🧡 and
v14.1.1