NumberField

The <NumberField> component used for capturing numerical input from the user in a form or similar input context. This allows users to input numbers including integers, decimals, and as well as percentages. The component also offers steppers which provides lower interaction costs.

Anatomy

It consists of a label, an input field and a help text. Optional you can also show a help text and stepper buttons for increasing/decreasing values.

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".

Numbers

Property	Type	Description
`variant`	`-`	The available variants of this component.
`size`	`-`	The available sizes of this component.

Usage

<NumberField> is an input field that accepts only numeric input.

Use Steppers

The stepper buttons make it easier and faster for people to make small numeric changes. It allows people to increase or decrease a number with a single button press, or by typing the number in the field.

Hide steppers

If you don't want the step buttons to appear, you can easily remove these with the hideStepper property.

Also keep in mind using the width property is essential to provide a good user experience. So each input field shouldn't be larger than the expected content. For example when using stepper buttons it is better to have shorter fields, so that the user can easier reach these buttons (lower interaction costs).

Preview

Code

Confirm Guests

Who’s going on your trip?

Adults

Children

Infants

Use steppers to make small numeric changes, else the interaction cost would be high.

Use Format Options

With <NumberField> you can use Intl.NumberFormatOptions which comes in handy to format the numbers in a certain format, e.g. percent,unit, decimal and currency.

For a full list of supported options, see corresponding MDN Docs. A full list of suported units can be seen here.

Preview

Code

Amount

Decimals

Length

Percentage

In addition, use units to support the label and make it clear what the user is entering in a particular number field.

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

Use short labels.

Don't

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.

Use label instead of a placeholder.

Don't

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.

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

Explain why certain information is needed.

NumberField 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

Never blame the user. Always be positive and helpful.

Don't

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

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

Charge

The charge is not allowed to be more than 1.000 €

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 NumberField stories

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-label?

string;

Defines a string value that labels the current element.

aria-labelledby?

string;

Identifies the element (or elements) that labels the current element.

autoFocus?

boolean;

Whether the element should receive focus on render.

decrementAriaLabel?

string;

A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used.

defaultValue?

number;

The default value (uncontrolled).

description?

ReactNode;

A helpful text.

dir?

string;

disabled?

boolean;

If true, the input is disabled.

Defaults to:

"false"

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.

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.

formatOptions?

NumberFormatOptions;

Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.

hidden?

boolean;

hideStepper?

boolean;

Property for hiding the step buttons of the field.

Defaults to:

"false"

id?

string;

The element's unique identifier. See MDN.

incrementAriaLabel?

string;

A custom aria-label for the increment button. If not provided, the localized string "Increment" is used.

inert?

boolean;

isWheelDisabled?

boolean;

Enables or disables changing the value with scroll.

label?

ReactNode;

Specifies the label of the field.

lang?

string;

maxValue?

number;

The largest value allowed for the input.

minValue?

number;

The smallest value allowed for the input.

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<Element, Element>) => void;

Handler that is called when the element loses focus.

onChange?

(value: number) => 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<Element, 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>;

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"

slot?

string | null;

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.

step?

number;

The amount that the input value changes with each increment or decrement "tick".

translate?

"yes" | "no";

validate?

(value: number) => 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?

number;

The current value (controlled).

width?

WidthProp;

Sets the width of the field. You can see allowed tokens here: https://tailwindcss.com/docs/width

Defaults to:

"full"

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.

Intl.NumberFormat

Enables language-sensitive number formatting.

NumericFormat

Helper component for formatting numeric based on the current language and locale-specific conventions.

Last update: a month ago

Anatomy

It consists of a label, an input field and a help text. Optional you can also show a help text and stepper buttons for increasing/decreasing values.

Appearance

Variant

Size

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

Numbers

Property	Type	Description
`variant`	`-`	The available variants of this component.
`size`	`-`	The available sizes of this component.

Usage

<NumberField> is an input field that accepts only numeric input.

Use Steppers

Hide steppers

If you don't want the step buttons to appear, you can easily remove these with the hideStepper property.

Preview

Code

Confirm Guests

Who’s going on your trip?

Adults

Children

Infants

Use steppers to make small numeric changes, else the interaction cost would be high.

Use Format Options

With <NumberField> you can use Intl.NumberFormatOptions which comes in handy to format the numbers in a certain format, e.g. percent,unit, decimal and currency.

For a full list of supported options, see corresponding MDN Docs. A full list of suported units can be seen here.

Preview

Code

Amount

Decimals

Length

Percentage

In addition, use units to support the label and make it clear what the user is entering in a particular number field.

Label

Use short labels.

Don't

Don’t use unnecessary instructional verbs.

Placeholder

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.

Use label instead of a placeholder.

Don't

Don’t use placeholder text instead of a label.

Additional Description

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

Explain why certain information is needed.

NumberField 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

Never blame the user. Always be positive and helpful.

Don't

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

Use detailed messages instead of global messages.

Preview

Code

Charge

The charge is not allowed to be more than 1.000 €

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 NumberField stories

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-label?

string;

Defines a string value that labels the current element.

aria-labelledby?

string;

Identifies the element (or elements) that labels the current element.

autoFocus?

boolean;

Whether the element should receive focus on render.

decrementAriaLabel?

string;

A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used.

defaultValue?

number;

The default value (uncontrolled).

description?

ReactNode;

A helpful text.

dir?

string;

disabled?

boolean;

If true, the input is disabled.

Defaults to:

"false"

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.

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.

formatOptions?

NumberFormatOptions;

Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.

hidden?

boolean;

hideStepper?

boolean;

Property for hiding the step buttons of the field.

Defaults to:

"false"

id?

string;

The element's unique identifier. See MDN.

incrementAriaLabel?

string;

A custom aria-label for the increment button. If not provided, the localized string "Increment" is used.

inert?

boolean;

isWheelDisabled?

boolean;

Enables or disables changing the value with scroll.

label?

ReactNode;

Specifies the label of the field.

lang?

string;

maxValue?

number;

The largest value allowed for the input.

minValue?

number;

The smallest value allowed for the input.

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<Element, Element>) => void;

Handler that is called when the element loses focus.

onChange?

(value: number) => 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<Element, 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>;

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>;

required?

boolean;

If true, the input is required.

Defaults to:

"false"

slot?

string | null;

step?

number;

The amount that the input value changes with each increment or decrement "tick".

translate?

"yes" | "no";

validate?

(value: number) => true | ValidationError | null;

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?

number;

The current value (controlled).

width?

WidthProp;

Sets the width of the field. You can see allowed tokens here: https://tailwindcss.com/docs/width

Defaults to:

"full"

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.

Intl.NumberFormat

Enables language-sensitive number formatting.

NumericFormat

Helper component for formatting numeric based on the current language and locale-specific conventions.

Last update: a month ago