Options
All
  • Public
  • Public/Protected
  • All
Menu

Module @react-md/form

Index

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

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

@since 2.5.0

Type declaration

    • (id: string, error: boolean): void
    • 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

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

A function that can be used to dynamically get an error icon based on the current visible error.

param

The current error message or an empty string

param

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

param

The current errorIcon that was provided to the useTextField hook.

returns

An icon to render or falsey to render nothing.

remarks

@since 2.5.0

Type declaration

    • (errorMessage: string, error: boolean, errorIcon: ReactNode): ReactNode
    • Parameters

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

      Returns ReactNode

GetErrorMessage

GetErrorMessage: (options: ErrorMessageOptions) => string

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.

param

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

returns

An error message to display or an empty string.

remarks

@since 2.5.0

Type declaration

GetIndeterminateControlledCheckboxProps

GetIndeterminateControlledCheckboxProps<T>: (value: T) => ProvidedIndeterminateControlledCheckboxProps<T>

The function that provides the props for each checkbox that is controlled by the root indeterminate checkbox.

Type parameters

  • T: string

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

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

param

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

returns

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

remarks

@since 2.5.0

Type declaration

ListboxChangeEventData

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

ListboxChangeEventHandler

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

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.

param

The next value that should be set for the listbox.

param

The option that was selected.

param

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

Type declaration

ListboxOption

ListboxOption: ListboxOptionProps | string | number | null

MenuItemCheckboxProps

MenuItemCheckboxProps: BaseMenuItemInputToggleProps
remarks

@since 2.8.0

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

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

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

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

Const DEFAULT_SLIDER_ANIMATION_TIME

DEFAULT_SLIDER_ANIMATION_TIME: 150 = 150
remarks

@since 2.5.0

Const DEFAULT_SLIDER_MAX

DEFAULT_SLIDER_MAX: 100 = 100
remarks

@since 2.5.0

Const DEFAULT_SLIDER_MIN

DEFAULT_SLIDER_MIN: 0 = 0
remarks

@since 2.5.0

Const DEFAULT_SLIDER_STEP

DEFAULT_SLIDER_STEP: 1 = 1
remarks

@since 2.5.0

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

Const FileInput

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

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

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

Const FormMessage

FormMessage: ForwardRefExoticComponent<FormMessageProps & Partial<FormMessageCounterProps> & 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".

Const 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

Const InputToggle

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

Const InputToggleIcon

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

@since 2.8.0

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

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

Const MenuItemCheckbox

MenuItemCheckbox: ForwardRefExoticComponent<BaseMenuItemInputToggleProps & 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>
  );
}

Const MenuItemInputToggle

MenuItemInputToggle: ForwardRefExoticComponent<MenuItemInputToggleProps & 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

Const 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

Const 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

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

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

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

Const 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

Const RECOMMENDED_NUMBER_STATE_KEYS

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

@since 2.5.0

Const RECOMMENDED_STATE_KEYS

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

@since 2.5.0

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

Const 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

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

Const 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

Const 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

Const 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

Const 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

Const Switch

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

Const 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

Const THUMB_1_VAR

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

@since 2.5.0

Const THUMB_2_VAR

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

@since 2.5.0

Const TextArea

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

Const 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

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

Const TextFieldAddon

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

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

Const TextFieldContainer

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

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

Const 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

Const 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

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

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

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>): [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 [T, ChangeEventHandler<E>, SetValue<T>]

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

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

  • useIndeterminateChecked<T>(values: T[], defaultCheckedValues?: T[] | (() => T[]), onChange?: (checkedValues: T[]) => void): IndeterminateCheckedReturnValue<T>
  • This hook allows you to toggle the state of multiple checkboxes in a single place along with an indeterminate checkbox that can check/uncheck all checkboxes at once.

    Examples:

    Simple value list with labels lookup:

    const values = ["a", "b", "c", "d"];
    const LABELS = { a: "Label 1", b: "Label 2", c: "Label 3", d: "Label 4" };
    const { getProps, rootProps } = useIndeterminateChecked(values);
    
    return (
      <>
        <Checkbox id="root-checkbox" {...rootProps} label="Root Checkbox" />
        {values.map((value, i) => (
          <Checkbox
            id={`child-checkbox-${i + 1}`}
            label={LABELS[value]}
            {...getProps(value)}
          />
        ))}
      </>
    );
    

    Fetch Data From Server and check first result

    interface ServerFetchedData {
      id: Guid;
      name: string;
    }
    
    
    const [data, setData] = useState<ServerFetchedData[]>([]);
    const { getProps, rootProps, setCheckedValues } = useIndeterminateChecked(
      data.map(({ id }) => id),
    );
    
    useEffect(() => {
      let cancelled = false;
      (async function load() {
        const response = await fetch("/my-api");
        const json = await response.json();
        if (!cancelled) {
          // pretend validation and sanity checks
          setData(json as ServerFetchedData[]);
          setCheckedValues(json[0].id);
        }
      })();
    
      return () => {
        cancelled = true;
      };
    }, []);
    
    return (
      <>
        <Checkbox id="root-checkbox" {...rootProps} label="Root Checkbox" />
        {data.map(({ id, name }, i) => (
          <Checkbox
            id={`child-checkbox-${i + 1}`}
            label={name}
            {...getProps(id)}
          />
        ))}
      </>
    );
    

    Type parameters

    • T: string

    Parameters

    • values: T[]

      All the checkbox values that the indeterminate checkbox can control. The values will need to be unique as they are passed to each checkbox to determine if it is checked or not. This will directly map to the value attribute for each checkbox.

    • defaultCheckedValues: T[] | (() => T[]) = []

      An optional list of all the values that are checked on first render. Changing this value will not update the checked values.

    • Optional onChange: (checkedValues: T[]) => void

      An optional function to call whenever the checked values list updates that will provide the next list of all the checked values. This isn't a super helpful prop since this hook will always return the checked values anyways.

        • (checkedValues: T[]): void
        • Parameters

          • checkedValues: T[]

          Returns void

    Returns IndeterminateCheckedReturnValue<T>

    An object containing a function to get the props for each controlled checkbox, the props for the root indeterminate checkbox, a list of all the checked values, and a general setCheckboxValues function from useState if the list of values can be changed from external sources as well.

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

Generated using TypeDoc