Options
All
  • Public
  • Public/Protected
  • All
Menu

Module @react-md/form

Index

Classes

Interfaces

Type aliases

Variables

Functions

Type aliases

ChangeValidationBehavior

ChangeValidationBehavior: boolean | "recommended" | "number-recommended" | keyof ValidityState | readonly keyof ValidityState[]

Since the default validation messages can be verbose, this type is used to configure when/how to display the native browser messages when the validation state changes during the change event phase. The validation message will always be shown on blur.

When this is:

  • true -> always show the browser message when it exists
  • false -> never show the browser message
  • "recommended" -> only shows the browser message if it is not one of the RECOMMENDED_IGNORED_KEYS validation errors
  • keyof ValidityState -> only shows the browser message if it is not the specific validation error
  • (keyof ValidityState)[] -> only shows the browser message if it is not the specific validation errors
remarks

@since 2.5.0

DefinedSliderValueOptions

DefinedSliderValueOptions: Required<SliderValueOptions>
remarks

@since 2.5.0

ErrorChangeHandler

ErrorChangeHandler: (id: string, error: boolean) => void

Type declaration

    • (id: string, error: boolean): void
    • A function that reports the error state changing. A good use-case for this is to keep track of all the errors within your form and keep a submit button disabled until they have been resolved.

      Example:

      const [errors, setErrors] = useState<Record<string, boolean | undefined>>({});
      const onErrorChange: ErrorChangeHandler = (id, error) =>
      setErrors((prevErrors) => ({ ...prevErrors, [id]: error }));

      const invalid = Object.values(errors).some(Boolean);

      // form implementation is left as an exercise for the reader
      <Button type="submit" disabled={invalid} onClick={submitForm}>Submit</Button>

      Parameters

      • id: string
      • error: boolean

      Returns void

FieldMessageContainerExtension

FieldMessageContainerExtension<P>: P & { messageContainerProps?: MessageContainerProps; messageProps?: MessageProps }

This is a utility type that allows for a component to "extend" the FieldMessageContainer component. This should really be used internally with any TextField or TextArea related components.

remarks

@since 2.5.0

Type parameters

  • P

FileReaderParser

FileReaderParser: "readAsText" | "readAsDataURL" | "readAsBinaryString" | "readAsArrayBuffer"

One of the function names from a FileReader to upload a file to the client.

Note: If this file does not need to be previewed in the browser and will immediately be uploaded to a server, use readAsArrayBuffer.

remarks

@since 2.9.0

FileReaderResult

FileReaderResult: FileReader["result"]
remarks

@since 2.9.0

FileUploadStats

remarks

@since 2.9.0

FileUploadStatus

FileUploadStatus: FileUploadStats["status"]
remarks

@since 2.9.0

FileValidationError

Mostly an internal type that is used to allow custom validation errors

remarks

@since 2.9.0

Type parameters

FilesValidator

FilesValidator<CustomError>: (files: readonly File[], options: FilesValidationOptions) => ValidatedFilesResult<CustomError>

Type parameters

  • CustomError = never

Type declaration

FixNumberOnBlur

FixNumberOnBlur: boolean | "min" | "max"

This is how the value within the text field should be "fixed" on blur. By default, the value will not be fixed and continue to display an error if there is an error.

If this is set to true, the value will be updated to be within the min and max values. Otherwise, setting this to min will only fix the minimum value while max will only fix the maximum.

remarks

@since 2.5.0

FormTheme

FormTheme: "none" | "underline" | "filled" | "outline"

The supported themes for the TextField, TextArea, and Select components.

  • "none" - display as an unstyled text field without any border or background colors.
  • "underline" - display with only an underline that gains the form active color and animates from the left or right to the other side when the field is focused.
  • "filled" - an extension of the "underline" state that will also have a slightly dark background applied.
  • "outline" - outlines the entire text field in a border and applies the active color as box shadow when the field is focused.

FormThemeContext

FormThemeContext: Required<FormThemeOptions>

FormUnderlineDirection

FormUnderlineDirection: "left" | "center" | "right"

The direction that the underline should appear from when the theme is "underline" or "filled".

GetErrorIcon

GetErrorIcon: (errorMessage: string, error: boolean, errorIcon: ReactNode) => ReactNode

Type declaration

    • (errorMessage: string, error: boolean, errorIcon: ReactNode): ReactNode
    • A function that can be used to dynamically get an error icon based on the current visible error.

      Parameters

      • errorMessage: string

        The current error message or an empty string

      • error: boolean

        Boolean if the TextField or TextArea are considered to be in an errored state

      • errorIcon: ReactNode

        The current errorIcon that was provided to the useTextField hook.

      Returns ReactNode

      An icon to render or falsey to render nothing.

GetErrorMessage

GetErrorMessage: (options: ErrorMessageOptions) => string

Type declaration

    • A function to get a custom error message for specific errors. This is really useful when using the pattern attribute to give additional information or changing the native "language translated" error message.

      Parameters

      • options: ErrorMessageOptions

        An object containing metadata that can be used to create an error message for your TextField or TextArea.

      Returns string

      An error message to display or an empty string.

GetFileParser

GetFileParser: (file: File) => FileReaderParser

Type declaration

GetVisibilityIcon

GetVisibilityIcon: (type: "text" | "password") => ReactNode

Type declaration

    • (type: "text" | "password"): ReactNode
    • Parameters

      • type: "text" | "password"

      Returns ReactNode

IsErrored

IsErrored: (options: IsErroredOptions) => boolean

Type declaration

    • A function that is used to determine if a TextField or TextArea is in an errored state.

      Parameters

      • options: IsErroredOptions

        All the current options that can be used to determine the error state.

      Returns boolean

      True if the component is considered to be in an errored state.

IsValidFileName

IsValidFileName: (file: File, extensionRegExp: RegExp | undefined, extendsions: readonly string[]) => boolean

Type declaration

    • (file: File, extensionRegExp: RegExp | undefined, extendsions: readonly string[]): boolean
    • This function is used to determine if a file should be added to the FileExtensionError. The default implementation should work for most use cases except when files that do not have extensions can be uploaded. i.e. LICENSE files.

      Parameters

      • file: File

        The file being checked

      • extensionRegExp: RegExp | undefined

        A regex that will only be defined if the extensions list had at least one value.

      • extendsions: readonly string[]

      Returns boolean

      true if the file has a valid name.

ListboxChangeEventData

ListboxChangeEventData: Pick<Required<ListboxProps>, "id" | "valueKey" | "value" | "options"> & Pick<ListboxProps, "name">

ListboxChangeEventHandler

ListboxChangeEventHandler: (nextValue: string, option: ListboxOption, listbox: ListboxChangeEventData) => void

Type declaration

    • A function to call when the value of the listbox changes. This will be called whenever the user clicks a new option within the select field with either the mouse, touch, or the enter/space key.

      Note: This will be called each time the user keyboard selects a new option by either typing to find a match, using the home/end keys, or using the arrow keys. If this is undesired behavior, enable the disableMovementChange prop so that it'll only be called on "click" events.

      Parameters

      • nextValue: string

        The next value that should be set for the listbox.

      • option: ListboxOption

        The option that was selected.

      • listbox: ListboxChangeEventData

        Part of the listbox props to help identify which listbox has been changed if reusing an event handler for multiple form parts.

      Returns void

ListboxOption

ListboxOption: ListboxOptionProps | string | number | null

MenuItemRadioProps

MenuItemRadioProps: BaseMenuItemInputToggleProps
remarks

@since 2.8.0

MenuItemSwitchProps

MenuItemSwitchProps: Omit<BaseMenuItemInputToggleProps, "icon">
remarks

@since 2.8.0

NumberFieldHookReturnType

NumberFieldHookReturnType: [number | undefined, ProvidedNumberFieldProps | ProvidedNumberFieldMessageProps, NumberFieldHookControls]

An ordered list containing:

remarks

@since 2.5.0

PasswordWithMessageProps

remarks

@since 2.5.0

RangeSliderDefaultValue

RangeSliderDefaultValue: RangeSliderValue | (() => RangeSliderValue)
remarks

@since 2.5.0

RangeSliderValue

RangeSliderValue: readonly [number, number]
remarks

@since 2.5.0

RangeSliderValueReturnType

RangeSliderValueReturnType: readonly [RangeSliderValue, RangeSliderRequiredProps]
remarks

@since 2.5.0

SliderDefaultValue

SliderDefaultValue: SliderValue | (() => SliderValue)
remarks

@since 2.5.0

SliderDragEvent

SliderDragEvent: MouseEvent | TouchEvent | React.MouseEvent | React.TouchEvent
remarks

@since 2.5.0

SliderDraggingBy

SliderDraggingBy: "mouse" | "touch" | null
remarks

@since 2.5.0

SliderEventHandlerNames

SliderEventHandlerNames: "onBlur" | "onKeyDown" | "onMouseDown" | "onTouchStart"
remarks

@since 2.5.0

SliderEventHandlers

SliderEventHandlers: Pick<HTMLAttributes<HTMLSpanElement>, SliderEventHandlerNames>
remarks

@since 2.5.0

SliderThumbIndex

SliderThumbIndex: ThumbIndex | null
remarks

@since 2.5.0

SliderThumbProps

SliderThumbProps: LabelRequiredForA11y<BaseThumbProps>
remarks

@since 2.5.0

SliderValue

SliderValue: number
remarks

@since 2.5.0

SliderValueReturnType

SliderValueReturnType: readonly [SliderValue, SliderRequiredProps]
remarks

@since 2.5.0

StrictMenuItemInputToggleProps

StrictMenuItemInputToggleProps: BaseMenuItemInputToggleProps & (({ type: "checkbox" } & IndeterminateCheckboxProps) | { indeterminate?: never; type: "radio" | "switch" })
remarks

@since 2.8.5

SupportedInputTypes

SupportedInputTypes: "text" | "password" | "number" | "tel" | "email" | "date" | "time" | "datetime-local" | "month" | "week" | "url" | "color" | "search"

These are all the "supported" input types for react-md so that they at least render reasonably well by default. There is no built-in validation or anything adding onto existing browser functionality for these types.

remarks

@since 2.5.0 - "search" was added

TextAreaResize

TextAreaResize: "none" | "auto" | "horizontal" | "vertical" | "both"

TextAreaWithMessageProps

remarks

@since 2.5.0

TextConstraints

TextConstraints: Pick<InputHTMLAttributes<HTMLInputElement>, "pattern" | "required" | "minLength" | "maxLength">
remarks

@since 2.5.0

TextFieldChangeHandlers

TextFieldChangeHandlers: Pick<HTMLAttributes<HTMLInputElement | HTMLTextAreaElement>, "onBlur" | "onChange">
remarks

@since 2.5.0

TextFieldHookReturnType

remarks

@since 2.5.0

TextFieldWithMessageProps

remarks

@since 2.5.0

ThumbIndex

ThumbIndex: 0 | 1
remarks

@since 2.5.0

Variables

AsyncSwitch

AsyncSwitch: ForwardRefExoticComponent<AsyncSwitchProps & RefAttributes<HTMLInputElement>> = ...

This component will create an async switch that will show a loading indicator and prevent the switch from being toggled while the loading state is true.

Checkbox

Checkbox: ForwardRefExoticComponent<CheckboxProps & RefAttributes<HTMLInputElement>> = ...

The Checkbox component is just a wrapper for the InputToggle that defaults to reasonable defaults for a checkbox input.

DEFAULT_SLIDER_ANIMATION_TIME

DEFAULT_SLIDER_ANIMATION_TIME: 150 = 150
remarks

@since 2.5.0

DEFAULT_SLIDER_MAX

DEFAULT_SLIDER_MAX: 100 = 100
remarks

@since 2.5.0

DEFAULT_SLIDER_MIN

DEFAULT_SLIDER_MIN: 0 = 0
remarks

@since 2.5.0

DEFAULT_SLIDER_STEP

DEFAULT_SLIDER_STEP: 1 = 1
remarks

@since 2.5.0

Fieldset

Fieldset: ForwardRefExoticComponent<FieldsetProps & RefAttributes<HTMLFieldSetElement>> = ...

This is a simple wrapper for the <fieldset> that defaults to removing the default styles of a border, padding, and margin and having a screen-reader visible only legend element for added accessibility.

FileInput

FileInput: ForwardRefExoticComponent<FileInputProps & RefAttributes<HTMLInputElement>> = ...

This component is a wrapper for the <input type="file" /> that can be themed like a button.

Form

Form: ForwardRefExoticComponent<FormProps & RefAttributes<HTMLFormElement>> = ...

This is probably one of the least useful components available as it doesn't do much styling or logic. All this form component will do is add basic flex behavior and prevent the default form submit behavior.

FormMessage

FormMessage: ForwardRefExoticComponent<FormMessageProps & Partial<FormMessageInputLengthCounterProps> & RefAttributes<HTMLDivElement>> = ...

The FormMessage component is used to create additional helper messages or error messages and generally placed below the related TextField. If a length (of the value) and maxLength are provided, a counter will also be displayed to the right of the children.

This component can also be used to create form-level validation messages by setting the role prop to "alert".

FormMessageContainer

FormMessageContainer: ForwardRefExoticComponent<FormMessageContainerProps & RefAttributes<HTMLDivElement>> = ...

A wrapper component that can be used to display a TextField related component or TextArea along with the FormMessage component.

remarks

@since 2.5.0

InputToggle

InputToggle: ForwardRefExoticComponent<(InputToggleProps & { type: "radio" } & RefAttributes<HTMLInputElement>) & (InputToggleProps & { indeterminate?: boolean; type: "checkbox" } & RefAttributes<HTMLInputElement>)> = ...

InputToggleIcon

InputToggleIcon: ForwardRefExoticComponent<InputToggleIconProps & RefAttributes<HTMLSpanElement>> = ...
remarks

@since 2.8.0

Label

Label: ForwardRefExoticComponent<LabelProps & RefAttributes<HTMLLabelElement>> = ...

The Label component should be used alongside any form elements but is already built in to the majority of the react-md components by default.

Listbox

Listbox: ForwardRefExoticComponent<ListboxProps & RefAttributes<ListElement>> = ...

This component is used to render the list part of a <select> element with built-in accessibility and the ability to add custom styles. This should probably not be used much outside of react-md itself and the Select component, but I'm planning on adding support for an inline listbox at some point.

MenuItemCheckbox

MenuItemCheckbox: ForwardRefExoticComponent<MenuItemCheckboxProps & RefAttributes<HTMLLIElement>> = ...

This is a simple wrapper for the MenuItemInputToggle component to render it as a checkbox and pulling the checkbox icon from the IconProvider.

example

Simple Example

import { ReactElement, useState } from "react";
import { DropdownMenu } from "@react-md/menu";
import { MenuItemCheckbox } from "@react-md/form";

function Example(): ReactElement {
const [checked, setChecked] = useState(false);

return (
<DropdownMenu
id="dropdown-menu-id"
items={[
<MenuItemCheckbox
id="checkbox-1"
checked={checked}
onCheckedChange={(nextChecked) => setChecked(nextChecked)}
>
Checkbox
</MenuItemCheckbox>,
]}
>
Button
</DropdownMenu>
);
}

MenuItemInputToggle

MenuItemInputToggle: ForwardRefExoticComponent<(BaseMenuItemInputToggleProps & { indeterminate?: undefined; type: "radio" | "switch" } & RefAttributes<HTMLLIElement>) & (BaseMenuItemInputToggleProps & { type: "checkbox" } & IndeterminateCheckboxProps & RefAttributes<HTMLLIElement>)> = ...

This is a low-level component that should probably not be used externally and instead the MenuItemCheckbox, MenuItemRadio, or MenuItemSwitch should be used instead.

see

MenuItemCheckbox for checkbox examples

see

MenuItemRadio for radio examples

see

MenuItemSwitch for switch examples

remarks

@since 2.8.0

MenuItemRadio

MenuItemRadio: ForwardRefExoticComponent<BaseMenuItemInputToggleProps & RefAttributes<HTMLLIElement>> = ...

This is a simple wrapper for the MenuItemInputToggle component to render it as a radio and pulling the radio icon from the IconProvider.

remarks

If a menu or menubar contains more than one group of menuitemradio elements, or if the menu contains one group and other, unrelated menu items, authors SHOULD nest each set of related menuitemradio elements in an element using the group role, and authors SHOULD delimit the group from other menu items with an element using the separator role.

see

https://www.w3.org/TR/wai-aria-1.1/#menuitemradio

example

Only Radio Items

import { ReactElement, useState } from "react";
import { DropdownMenu } from "@react-md/menu";
import { MenuItemRadio } from "@react-md/form";

function Example(): ReactElement {
const [value, setValue] = useState("value1");

return (
<DropdownMenu
id="dropdown-menu-id"
items={[
<MenuItemRadio
id="radio-1"
checked={value === "value1"}
onCheckedChange={() => setValue("value1")}
>
Radio 1
</MenuItemRadio>,
<MenuItemRadio
id="radio-2"
checked={value === "value2"}
onCheckedChange={() => setValue("value2")}
>
Radio 2
</MenuItemRadio>,
<MenuItemRadio
id="radio-3"
checked={value === "value3"}
onCheckedChange={() => setValue("value3")}
>
Radio 3
</MenuItemRadio>,
]}
>
Button
</DropdownMenu>
);
}
example

With Other Items

import { ReactElement, useState } from "react";
import { DropdownMenu, MenuItemSeparator } from "@react-md/menu";
import { MenuItemRadio, MenuItemSwitch } from "@react-md/form";

function Example(): ReactElement {
const [value, setValue] = useState("value1");

return (
<DropdownMenu
id="dropdown-menu-id"
items={[
<MenuItemSwitch
id="switch-id"
checked={checked}
onCheckedChange={nextChecked => setChecked(nextChecked)}
>
Light mode
</MenuItemSwitch>,
<MenuItemSeparator />,
<div role="group" aria-label="My Group Label">
<MenuItemRadio
id="radio-1"
checked={value === "value1"}
onCheckedChange={() => setValue("value1")}
>
Radio 1
</MenuItemRadio>,
<MenuItemRadio
id="radio-2"
checked={value === "value2"}
onCheckedChange={() => setValue("value2")}
>
Radio 2
</MenuItemRadio>,
<MenuItemRadio
id="radio-3"
checked={value === "value3"}
onCheckedChange={() => setValue("value3")}
>
Radio 3
</MenuItemRadio>
</div>,
]}
>
Button
</DropdownMenu>
);
}
remarks

@since 2.8.0

MenuItemSwitch

MenuItemSwitch: ForwardRefExoticComponent<MenuItemSwitchProps & RefAttributes<HTMLLIElement>> = ...

This is a simple wrapper for the MenuItemInputToggle component to render it as a switch.

example

Simple Example

import { ReactElement, useState } from "react";
import { DropdownMenu } from "@react-md/menu";
import { MenuItemSwitch } from "@react-md/form";

function Example(): ReactElement {
const [checked, setChecked] = useState(false);

return (
<DropdownMenu
id="dropdown-menu-id"
items={[
<MenuItemSwitch
id="switch-1"
checked={checked}
onCheckedChange={(nextChecked) => setChecked(nextChecked)}
>
Switch
</MenuItemSwitch>,
]}
>
Button
</DropdownMenu>
);
}
remarks

@since 2.8.0

NativeSelect

NativeSelect: ForwardRefExoticComponent<NativeSelectProps & RefAttributes<HTMLSelectElement>> = ...

This component is used to render a native <select> element with the text field theme styles. This component is great to use for native behavior and full accessibility.

Option

Option: ForwardRefExoticComponent<OptionProps & RefAttributes<HTMLLIElement>> = ...

The Option component is a simple wrapper for the SimpleListItem that adds some required a11y for behaving as the option role.

Password

Password: ForwardRefExoticComponent<PasswordProps & RefAttributes<HTMLInputElement>> = ...

This component is a simple wrapper of the TextField that can only be rendered for password inputs. There is built-in functionality to be able to temporarily show the password's value by swapping the type to "text".

PasswordWithMessage

PasswordWithMessage: ForwardRefExoticComponent<PasswordProps & { messageContainerProps?: MessageContainerProps; messageProps?: MessageProps } & RefAttributes<HTMLInputElement>> = ...

This component is a simple wrapper for the Password and FormMessage components that should be used along with the useTextField hook to conditionally show help and error messages with a Password.

Simple example:

const [value, fieldProps] = useTextField({
id: "field-id",
required: true,
minLength: 10,
});

return (
<PasswordWithMessage
label="Label"
placeholder="Placeholder"
{...fieldProps}
/>
);

Note: Unline the TextFieldWithMessage and TextAreaWithMessage, the error icon will do nothing for this component unless the disableVisibility prop is enabled.

remarks

@since 2.5.0

RECOMMENDED_NUMBER_STATE_KEYS

RECOMMENDED_NUMBER_STATE_KEYS: readonly keyof ValidityState[] = ...
internal
remarks

@since 2.5.0

RECOMMENDED_STATE_KEYS

RECOMMENDED_STATE_KEYS: readonly keyof ValidityState[] = ...
internal
remarks

@since 2.5.0

Radio

Radio: ForwardRefExoticComponent<RadioProps & RefAttributes<HTMLInputElement>> = ...

The Radio component is just a wrapper for the InputToggle that defaults to reasonable defaults for a radio input.

RangeSlider

RangeSlider: ForwardRefExoticComponent<RangeSliderProps & RefAttributes<HTMLDivElement>> = ...

The RangeSlider component allows the user to select a min and max value from a predefined range of numbers. The functionality for controlling the value of this component is provided by the useRangeSlider hook.

remarks

@since 2.5.0

Select

Select: ForwardRefExoticComponent<SelectProps & RefAttributes<HTMLDivElement>> = ...

This component is an accessible version of the <select> element that allows for some more custom styles by using the @react-md/list package to render the list of options.

The Select component must be controlled with a value and onChange handler.

Note: Since this is not a native <select> component, the current value will be rendered in an <input type="hidden" /> element so that the value can be sent along in forms. It is highly recommended to always provide a name prop so this value is sent.

Slider

Slider: ForwardRefExoticComponent<SliderProps & RefAttributes<HTMLDivElement>> = ...

The Slider component allows the user to select a single value from a range of numbers. The functionality for controlling the value of this component is provided by the useSlider hook.

remarks

@since 2.5.0

SliderContainer

SliderContainer: ForwardRefExoticComponent<SliderContainerProps & RefAttributes<HTMLDivElement>> = ...

The SliderContainer component is mostly an interal component that is built-in to the Slider and RangeSlider components to add addons to the left or right of the SliderTrack. When vertical, it will add addons to the bottom or top instead.

remarks

@since 2.5.0

SliderThumb

SliderThumb: ForwardRefExoticComponent<(Pick<BaseThumbProps, "vertical" | "className" | "children" | "id" | "defaultChecked" | "defaultValue" | "suppressContentEditableWarning" | "suppressHydrationWarning" | "accessKey" | "contentEditable" | "contextMenu" | "dir" | "draggable" | "hidden" | "lang" | "placeholder" | "slot" | "spellCheck" | "style" | "tabIndex" | "title" | "translate" | "radioGroup" | "role" | "about" | "datatype" | "inlist" | "prefix" | "property" | "resource" | "typeof" | "vocab" | "autoCapitalize" | "autoCorrect" | "autoSave" | "color" | "itemProp" | "itemScope" | "itemType" | "itemID" | "itemRef" | "results" | "security" | "unselectable" | "inputMode" | "is" | "aria-activedescendant" | "aria-atomic" | "aria-autocomplete" | "aria-busy" | "aria-checked" | "aria-colcount" | "aria-colindex" | "aria-colspan" | "aria-controls" | "aria-current" | "aria-describedby" | "aria-details" | "aria-disabled" | "aria-dropeffect" | "aria-errormessage" | "aria-expanded" | "aria-flowto" | "aria-grabbed" | "aria-haspopup" | "aria-hidden" | "aria-invalid" | "aria-keyshortcuts" | "aria-level" | "aria-live" | "aria-modal" | "aria-multiline" | "aria-multiselectable" | "aria-orientation" | "aria-owns" | "aria-placeholder" | "aria-posinset" | "aria-pressed" | "aria-readonly" | "aria-relevant" | "aria-required" | "aria-roledescription" | "aria-rowcount" | "aria-rowindex" | "aria-rowspan" | "aria-selected" | "aria-setsize" | "aria-sort" | "aria-valuemax" | "aria-valuemin" | "aria-valuenow" | "aria-valuetext" | "dangerouslySetInnerHTML" | "onCopy" | "onCopyCapture" | "onCut" | "onCutCapture" | "onPaste" | "onPasteCapture" | "onCompositionEnd" | "onCompositionEndCapture" | "onCompositionStart" | "onCompositionStartCapture" | "onCompositionUpdate" | "onCompositionUpdateCapture" | "onFocus" | "onFocusCapture" | "onBlur" | "onBlurCapture" | "onChange" | "onChangeCapture" | "onBeforeInput" | "onBeforeInputCapture" | "onInput" | "onInputCapture" | "onReset" | "onResetCapture" | "onSubmit" | "onSubmitCapture" | "onInvalid" | "onInvalidCapture" | "onLoad" | "onLoadCapture" | "onError" | "onErrorCapture" | "onKeyDown" | "onKeyDownCapture" | "onKeyPress" | "onKeyPressCapture" | "onKeyUp" | "onKeyUpCapture" | "onAbort" | "onAbortCapture" | "onCanPlay" | "onCanPlayCapture" | "onCanPlayThrough" | "onCanPlayThroughCapture" | "onDurationChange" | "onDurationChangeCapture" | "onEmptied" | "onEmptiedCapture" | "onEncrypted" | "onEncryptedCapture" | "onEnded" | "onEndedCapture" | "onLoadedData" | "onLoadedDataCapture" | "onLoadedMetadata" | "onLoadedMetadataCapture" | "onLoadStart" | "onLoadStartCapture" | "onPause" | "onPauseCapture" | "onPlay" | "onPlayCapture" | "onPlaying" | "onPlayingCapture" | "onProgress" | "onProgressCapture" | "onRateChange" | "onRateChangeCapture" | "onSeeked" | "onSeekedCapture" | "onSeeking" | "onSeekingCapture" | "onStalled" | "onStalledCapture" | "onSuspend" | "onSuspendCapture" | "onTimeUpdate" | "onTimeUpdateCapture" | "onVolumeChange" | "onVolumeChangeCapture" | "onWaiting" | "onWaitingCapture" | "onAuxClick" | "onAuxClickCapture" | "onClick" | "onClickCapture" | "onContextMenu" | "onContextMenuCapture" | "onDoubleClick" | "onDoubleClickCapture" | "onDrag" | "onDragCapture" | "onDragEnd" | "onDragEndCapture" | "onDragEnter" | "onDragEnterCapture" | "onDragExit" | "onDragExitCapture" | "onDragLeave" | "onDragLeaveCapture" | "onDragOver" | "onDragOverCapture" | "onDragStart" | "onDragStartCapture" | "onDrop" | "onDropCapture" | "onMouseDown" | "onMouseDownCapture" | "onMouseEnter" | "onMouseLeave" | "onMouseMove" | "onMouseMoveCapture" | "onMouseOut" | "onMouseOutCapture" | "onMouseOver" | "onMouseOverCapture" | "onMouseUp" | "onMouseUpCapture" | "onSelect" | "onSelectCapture" | "onTouchCancel" | "onTouchCancelCapture" | "onTouchEnd" | "onTouchEndCapture" | "onTouchMove" | "onTouchMoveCapture" | "onTouchStart" | "onTouchStartCapture" | "onPointerDown" | "onPointerDownCapture" | "onPointerMove" | "onPointerMoveCapture" | "onPointerUp" | "onPointerUpCapture" | "onPointerCancel" | "onPointerCancelCapture" | "onPointerEnter" | "onPointerEnterCapture" | "onPointerLeave" | "onPointerLeaveCapture" | "onPointerOver" | "onPointerOverCapture" | "onPointerOut" | "onPointerOutCapture" | "onGotPointerCapture" | "onGotPointerCaptureCapture" | "onLostPointerCapture" | "onLostPointerCaptureCapture" | "onScroll" | "onScrollCapture" | "onWheel" | "onWheelCapture" | "onAnimationStart" | "onAnimationStartCapture" | "onAnimationEnd" | "onAnimationEndCapture" | "onAnimationIteration" | "onAnimationIterationCapture" | "onTransitionEnd" | "onTransitionEndCapture" | "animate" | "disabled" | "name" | "value" | "max" | "min" | "active" | "baseId" | "discrete" | "getValueText" | "animationDuration" | "index"> & Required<Pick<BaseThumbProps, "aria-label">> & Partial<Pick<BaseThumbProps, "aria-labelledby">> & RefAttributes<HTMLSpanElement>) & (Pick<BaseThumbProps, "vertical" | "className" | "children" | "id" | "defaultChecked" | "defaultValue" | "suppressContentEditableWarning" | "suppressHydrationWarning" | "accessKey" | "contentEditable" | "contextMenu" | "dir" | "draggable" | "hidden" | "lang" | "placeholder" | "slot" | "spellCheck" | "style" | "tabIndex" | "title" | "translate" | "radioGroup" | "role" | "about" | "datatype" | "inlist" | "prefix" | "property" | "resource" | "typeof" | "vocab" | "autoCapitalize" | "autoCorrect" | "autoSave" | "color" | "itemProp" | "itemScope" | "itemType" | "itemID" | "itemRef" | "results" | "security" | "unselectable" | "inputMode" | "is" | "aria-activedescendant" | "aria-atomic" | "aria-autocomplete" | "aria-busy" | "aria-checked" | "aria-colcount" | "aria-colindex" | "aria-colspan" | "aria-controls" | "aria-current" | "aria-describedby" | "aria-details" | "aria-disabled" | "aria-dropeffect" | "aria-errormessage" | "aria-expanded" | "aria-flowto" | "aria-grabbed" | "aria-haspopup" | "aria-hidden" | "aria-invalid" | "aria-keyshortcuts" | "aria-level" | "aria-live" | "aria-modal" | "aria-multiline" | "aria-multiselectable" | "aria-orientation" | "aria-owns" | "aria-placeholder" | "aria-posinset" | "aria-pressed" | "aria-readonly" | "aria-relevant" | "aria-required" | "aria-roledescription" | "aria-rowcount" | "aria-rowindex" | "aria-rowspan" | "aria-selected" | "aria-setsize" | "aria-sort" | "aria-valuemax" | "aria-valuemin" | "aria-valuenow" | "aria-valuetext" | "dangerouslySetInnerHTML" | "onCopy" | "onCopyCapture" | "onCut" | "onCutCapture" | "onPaste" | "onPasteCapture" | "onCompositionEnd" | "onCompositionEndCapture" | "onCompositionStart" | "onCompositionStartCapture" | "onCompositionUpdate" | "onCompositionUpdateCapture" | "onFocus" | "onFocusCapture" | "onBlur" | "onBlurCapture" | "onChange" | "onChangeCapture" | "onBeforeInput" | "onBeforeInputCapture" | "onInput" | "onInputCapture" | "onReset" | "onResetCapture" | "onSubmit" | "onSubmitCapture" | "onInvalid" | "onInvalidCapture" | "onLoad" | "onLoadCapture" | "onError" | "onErrorCapture" | "onKeyDown" | "onKeyDownCapture" | "onKeyPress" | "onKeyPressCapture" | "onKeyUp" | "onKeyUpCapture" | "onAbort" | "onAbortCapture" | "onCanPlay" | "onCanPlayCapture" | "onCanPlayThrough" | "onCanPlayThroughCapture" | "onDurationChange" | "onDurationChangeCapture" | "onEmptied" | "onEmptiedCapture" | "onEncrypted" | "onEncryptedCapture" | "onEnded" | "onEndedCapture" | "onLoadedData" | "onLoadedDataCapture" | "onLoadedMetadata" | "onLoadedMetadataCapture" | "onLoadStart" | "onLoadStartCapture" | "onPause" | "onPauseCapture" | "onPlay" | "onPlayCapture" | "onPlaying" | "onPlayingCapture" | "onProgress" | "onProgressCapture" | "onRateChange" | "onRateChangeCapture" | "onSeeked" | "onSeekedCapture" | "onSeeking" | "onSeekingCapture" | "onStalled" | "onStalledCapture" | "onSuspend" | "onSuspendCapture" | "onTimeUpdate" | "onTimeUpdateCapture" | "onVolumeChange" | "onVolumeChangeCapture" | "onWaiting" | "onWaitingCapture" | "onAuxClick" | "onAuxClickCapture" | "onClick" | "onClickCapture" | "onContextMenu" | "onContextMenuCapture" | "onDoubleClick" | "onDoubleClickCapture" | "onDrag" | "onDragCapture" | "onDragEnd" | "onDragEndCapture" | "onDragEnter" | "onDragEnterCapture" | "onDragExit" | "onDragExitCapture" | "onDragLeave" | "onDragLeaveCapture" | "onDragOver" | "onDragOverCapture" | "onDragStart" | "onDragStartCapture" | "onDrop" | "onDropCapture" | "onMouseDown" | "onMouseDownCapture" | "onMouseEnter" | "onMouseLeave" | "onMouseMove" | "onMouseMoveCapture" | "onMouseOut" | "onMouseOutCapture" | "onMouseOver" | "onMouseOverCapture" | "onMouseUp" | "onMouseUpCapture" | "onSelect" | "onSelectCapture" | "onTouchCancel" | "onTouchCancelCapture" | "onTouchEnd" | "onTouchEndCapture" | "onTouchMove" | "onTouchMoveCapture" | "onTouchStart" | "onTouchStartCapture" | "onPointerDown" | "onPointerDownCapture" | "onPointerMove" | "onPointerMoveCapture" | "onPointerUp" | "onPointerUpCapture" | "onPointerCancel" | "onPointerCancelCapture" | "onPointerEnter" | "onPointerEnterCapture" | "onPointerLeave" | "onPointerLeaveCapture" | "onPointerOver" | "onPointerOverCapture" | "onPointerOut" | "onPointerOutCapture" | "onGotPointerCapture" | "onGotPointerCaptureCapture" | "onLostPointerCapture" | "onLostPointerCaptureCapture" | "onScroll" | "onScrollCapture" | "onWheel" | "onWheelCapture" | "onAnimationStart" | "onAnimationStartCapture" | "onAnimationEnd" | "onAnimationEndCapture" | "onAnimationIteration" | "onAnimationIterationCapture" | "onTransitionEnd" | "onTransitionEndCapture" | "animate" | "disabled" | "name" | "value" | "max" | "min" | "active" | "baseId" | "discrete" | "getValueText" | "animationDuration" | "index"> & Required<Pick<BaseThumbProps, "aria-labelledby">> & Partial<Pick<BaseThumbProps, "aria-label">> & RefAttributes<HTMLSpanElement>)> = ...

The slider thumb implements the role="slider" for the Slider and RangeSlider components.

remarks

@since 2.5.0

SliderTrack

SliderTrack: ForwardRefExoticComponent<SliderTrackProps & RefAttributes<HTMLSpanElement>> = ...

The SliderTrack component is used to show the distance that the slider can be dragged as well as a visual indication of the value. The main usage is to update the custom css properties for the thumb's values.

remarks

@since 2.5.0

Switch

Switch: ForwardRefExoticComponent<SwitchProps & RefAttributes<HTMLInputElement>> = ...

SwitchTrack

SwitchTrack: ForwardRefExoticComponent<SwitchTrackProps & RefAttributes<HTMLInputElement>> = ...

This is most likely an internal only component that is used to render the switch element either as a checkbox or in the MenuItemSwitch component.

remarks

@since 2.8.0

THUMB_1_VAR

THUMB_1_VAR: "--offset1" = "--offset1"
remarks

@since 2.5.0

THUMB_2_VAR

THUMB_2_VAR: "--offset2" = "--offset2"
remarks

@since 2.5.0

TextArea

TextArea: ForwardRefExoticComponent<TextAreaProps & RefAttributes<HTMLTextAreaElement>> = ...

TextAreaWithMessage

TextAreaWithMessage: ForwardRefExoticComponent<TextAreaProps & { messageContainerProps?: MessageContainerProps; messageProps?: MessageProps } & RefAttributes<HTMLTextAreaElement>> = ...

This component is a simple wrapper for the TextArea and FormMessage components that should be used along with the useTextField hook to conditionally show help and error messages with a TextArea.

Simple example:

const [value, areaProps] = useTextField({
id: "area-id",
});

return (
<TextFieldWithMessage
label="Label"
placeholder="Placeholder"
{...areaProps}
/>
);
remarks

@since 2.5.0

TextField

TextField: ForwardRefExoticComponent<TextFieldProps & RefAttributes<HTMLInputElement>> = ...

The text field is a wrapper of the <input type="text" /> component with some nice default themes. It can also be used to render other text input types with some support.

TextFieldAddon

TextFieldAddon: ForwardRefExoticComponent<TextFieldAddonProps & RefAttributes<HTMLSpanElement>> = ...

This component is used to add an an icon before or after the text field with correct styling.

TextFieldContainer

TextFieldContainer: ForwardRefExoticComponent<TextFieldContainerProps & RefAttributes<HTMLDivElement>> = ...

This is a container component that is used to structure the text field with different parts and themes.

TextFieldWithMessage

TextFieldWithMessage: ForwardRefExoticComponent<TextFieldProps & { messageContainerProps?: MessageContainerProps; messageProps?: MessageProps } & RefAttributes<HTMLInputElement>> = ...

This component is a simple wrapper for the TextField and FormMessage components that should be used along with the useTextField hook to conditionally show help and error messages with a TextField.

Simple example:

const [value, fieldProps] = useTextField({
id: "field-id",
});

return (
<TextFieldWithMessage
label="Label"
placeholder="Placeholder"
{...fieldProps}
/>
);
remarks

@since 2.5.0

ToggleContainer

ToggleContainer: ForwardRefExoticComponent<ToggleContainerProps & RefAttributes<HTMLDivElement>> = ...

The ToggleContainer component should generally be used around a custom "checkbox", "radio", or "switch" component to help with additional styles. This is mostly an internal component so I'm not sure useful it will be though.

Functions

DEFAULT_GET_DISPLAY_LABEL

  • DEFAULT_GET_DISPLAY_LABEL(option: ListboxOption, labelKey: string, includeLeft: boolean): ReactNode
  • A function that will get the display value for the Select field based on the current selected option. The default behavior will be to return null if an option is not currently selected so the placeholder text can be shown instead. If there is an option selected, it will:

    • get the option's label using the general getOptionLabel util
    • check if includeLeft is enabled and the option is an object with leftAddon
      • if there is a leftAddon, use the TextIconSpacing of the label + the icon or avatar.

    Parameters

    • option: ListboxOption

      The option to get a display label for

    • labelKey: string

      The key to use to extract a label from the option when it is an object

    • includeLeft: boolean

      Boolean if a leftAddon should be added with TextIconSpacing to the result.

    Returns ReactNode

    A renderable node to display in a Select field.

DEFAULT_GET_OPTION_ID

  • DEFAULT_GET_OPTION_ID(baseId: string, index: number): string
  • The default way to generate a "unique" id for each option within the listbox by concatenating the current index with a base id.

    Note: The index will be incremented by 1 so the ids start from 1 instead of 0. This is so that it matches how paginated results work with aria-posinset

    • aria-setsize.

    Parameters

    • baseId: string

      The base id of the listbox.

    • index: number

      The current index of the option

    Returns string

    a "unique" id for the option

DEFAULT_GET_OPTION_LABEL

  • DEFAULT_GET_OPTION_LABEL(option: ListboxOption, labelKey: string): ReactNode
  • A function that will get the label for an option. The default behavior is to check if the option is an object. If it is, it'll use the labelKey property and fallback to the children property. If it is anything else, the option itself will be returned.

    This is used in both the select's button element to show the current value as well as rendering each option within the listbox component.

    Parameters

    • option: ListboxOption

      The option that should be converted into a renderable label element.

    • labelKey: string

      The object key to use to extract the label from an option object.

    Returns ReactNode

    a renderable label to display.

Const DEFAULT_SLIDER_GET_VALUE_TEXT

  • DEFAULT_SLIDER_GET_VALUE_TEXT(): string

FormMessageCounter

  • This component can be used to create a "counter" within the FormMessage component.

    Note: This is really only useful when using the FormMessage component without a TextField.

    example

    Example Usage

    interface ExampleProps {
    min: number;
    max: number;
    }

    function Example({ min, max }: ExampleProps) {
    return (
    <FormMessage disableWrap>
    <FormMessageCounter>
    {`${min} / ${max}`}
    </FormMessageCounter>
    </FormMessage>
    );
    }
    remarks

    @since 2.9.0

    Parameters

    Returns ReactElement

FormThemeProvider

Const defaultGetErrorIcon

  • defaultGetErrorIcon(errorMessage: string, error: boolean, errorIcon: ReactNode): ReactNode
  • The default implementation for showing an error icon in TextField and TextArea components that will only display when the error flag is enabled.

    remarks

    @since 2.5.0

    Parameters

    • errorMessage: string
    • error: boolean
    • errorIcon: ReactNode

    Returns ReactNode

Const defaultGetErrorMessage

Const defaultIsErrored

  • The default implementation for checking if a TextField or TextArea is errored by returning true if the errorMessage string is truthy or the value is not within the minLength and maxLength constraints when they exist.

    remarks

    @since 2.5.0

    Parameters

    Returns boolean

Const getFileParser

  • This function will attempt to read:

    • media (image, audio, and video) files as a data url so they can be previewed in <img>, <audio>, and <video> tags
    • text files as plain text
    • everything else as an ArrayBuffer which can be manually converted into a data url if needed with URL.createObjectURL
    remarks

    @since 2.9.0

    Parameters

    • file: File

    Returns FileReaderParser

getSplitFileUploads

isAudioFile

  • isAudioFile(file: File): boolean
  • This will first check if the mime-type of the file starts with audio/ and fallback to checking a few file names or extensions that should be considered audio.

    This function is not guaranteed to be 100% correct and is only useful if trying to generate a preview of files uploaded to the browser.

    remarks

    @since 2.9.0

    Parameters

    • file: File

      The file to check

    Returns boolean

    true if the file should be considered as a audio content file.

isFileAccessError

isFileExtensionError

isFileSizeError

isGenericFileError

isImageFile

  • isImageFile(file: File): boolean
  • This will first check if the mime-type of the file starts with text\/ and fallback to checking a few file names or extensions that should be considered text.

    This function is not guaranteed to be 100% correct and is only useful if trying to generate a preview of files uploaded to the browser.

    remarks

    @since 2.9.0

    Parameters

    • file: File

      The file to check

    Returns boolean

    true if the file should be considered as a text content file.

isListboxOptionProps

  • A type guard that simply checks if the option is considered an object of list item props.

    internal

    Parameters

    Returns option is ListboxOptionProps

    true if the option is considered a object of list item props and will ensure that the option is typed as ListboxOptionProps

isMediaFile

  • isMediaFile(file: File): boolean
  • This function is not guaranteed to be 100% correct and is only useful if trying to generate a preview of files uploaded to the browser.

    remarks

    @since 2.9.0

    Parameters

    • file: File

      The file to check

    Returns boolean

    true if the file matches an image, audio, or video file.

isTextFile

  • isTextFile(file: File): boolean
  • This will first check if the mime-type of the file starts with text/ and fallback to checking a few file names or extensions that should be considered text.

    This function is not guaranteed to be 100% correct and is only useful if trying to generate a preview of files uploaded to the browser.

    remarks

    @since 2.9.0

    Parameters

    • file: File

      The file to check

    Returns boolean

    true if the file should be considered as a text-content file.

isTooManyFilesError

Const isValidFileName

  • isValidFileName(file: File, extensionRegExp: undefined | RegExp, extendsions: readonly string[]): boolean
  • defaultvalue

    matcher?.test(file.name) ?? true

    remarks

    @since 3.1.0

    Parameters

    • file: File
    • extensionRegExp: undefined | RegExp
    • extendsions: readonly string[]

    Returns boolean

isVideoFile

  • isVideoFile(file: File): boolean
  • This will first check if the mime-type of the file starts with video/ and fallback to checking a few file names or extensions that should be considered video.

    This function is not guaranteed to be 100% correct and is only useful if trying to generate a preview of files uploaded to the browser.

    remarks

    @since 2.9.0

    Parameters

    • file: File

      The file to check

    Returns boolean

    true if the file should be considered as a video content file.

Const labelStyles

  • A simple util that can generate all the "valid" styles for a label. This shouldn't really be used, but it's useful if you want the label styles without rendering a <label> element.

    remarks

    @since 2.5.0

    internal

    Parameters

    Returns string

useChecked

  • useChecked(defaultChecked: boolean | (() => boolean), onChange?: ChangeEventHandler): [boolean, ChangeEventHandler, SetChecked]
  • A small hook that can be used for controlling the state of a single Checkbox component.

    Parameters

    • defaultChecked: boolean | (() => boolean)

      Boolean if the input should be checked by default. Changing this value will not update the state after initial render.

    • Optional onChange: ChangeEventHandler

      An optional change event handler to also call when the checked state changes.

    Returns [boolean, ChangeEventHandler, SetChecked]

    a list containing the checked state, a change event handler, and then a manual set checked action.

useChoice

  • useChoice<T, E>(defaultValue: T, onChange?: ChangeEventHandler<E>): readonly [T, ChangeEventHandler<E>, SetValue<T>]
  • This hook can be used to control the state of a radio group or a select element.

    Type parameters

    • T: DefaultValue = DefaultValue

    • E: InputElement = InputElement

    Parameters

    • defaultValue: T

      The default value. If you want the user to specifically choose a value, set this to the empty string.

    • Optional onChange: ChangeEventHandler<E>

      An optional change event handler to also call when the change event is triggered.

    Returns readonly [T, ChangeEventHandler<E>, SetValue<T>]

    a list containing the current value, a change event handler, and then a manual value setter.

useFileUpload

  • This hook is generally used to upload files to the browser in different formats to be previewed <img>, <video>, <embed>, etc tags. However, it can also be used to upload the files as an ArrayBuffer and then uploaded to a server.

    Note: If using the aws-sdk to upload files directly to S3, do not use this hook since it uses its own upload process.

    remarks

    @since 2.9.0

    Type parameters

    • E: HTMLElement

      An optional HTMLElement type that is used for the FileUploadHandlers.

    • CustomError = never

      An optional error type that gets returned from the FilesValidator.

    Parameters

    Returns Readonly<FileUploadHookReturnValue<E, CustomError>>

useFormTheme

  • Gets the current theme values for a form component by inheriting the current form theme via context. If you provide an object of theme props, the returned value will use any defined values from the theme props and fallback to the context value.

    Example:

    // everything is inherited
    const formTheme = useFormTheme();

    // theme will be set to "underline" while the others will be inherited
    const formTheme = useFormTheme({ theme: "underline" });

    Parameters

    Returns FormThemeContext

useIndeterminateChecked

useNumberField

useRangeSlider

  • This hook is used to control the value and behavior of the RangeSlider component. The first argument will contain the current slider value while the second argument will be all the props required to control the RangeSlider component.

    remarks

    @since 2.5.0

    Parameters

    Returns RangeSliderValueReturnType

    an ordered list containing the current value followed by the RangeSlider props

useSelectState

  • useSelectState<T>(defaultValue: DefaultValue<T>): ReturnValue<T>
  • This is a simple hook that will allow you to "strongly" type a Select component's value since the onChange handler only returns a string.

    Type parameters

    • T: string

    Parameters

    • defaultValue: DefaultValue<T>

      The default value to use

    Returns ReturnValue<T>

    an ordered list containing the current value followed by the dispatch function to update the state.

useSlider

  • This hook is used to control the value and behavior of the Slider component. The first argument will contain the current slider value while the second argument will be all the props required to control the Slider component.

    remarks

    @since 2.5.0

    Parameters

    • Optional defaultValue: SliderDefaultValue

      An optional default value to use for the slider. This will default to the min option when undefined.

    • __namedParameters: UseSliderOptions = {}

    Returns SliderValueReturnType

    an ordered list containing the current value followed by the Slider props

useTextField

validateFiles

Generated using TypeDoc