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>
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.
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.
Mostly an internal type that is used to allow custom validation errors
This function will be called whenever a file has been uploaded by the user
either through an <input type="file"> or drag and drop behavior.
The list of files to check
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.
The supported themes for the TextField, TextArea, and Select
components.
"underline" state that will also have a
slightly dark background applied.The direction that the underline should appear from when the theme is
"underline" or "filled".
A function that can be used to dynamically get an error icon based on the current visible error.
The current error message or an empty string
Boolean if the TextField or TextArea are considered to be
in an errored state
The current errorIcon that was provided to the
useTextField hook.
An icon to render or falsey to render nothing.
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.
An object containing metadata that can be used to create an
error message for your TextField or TextArea.
An error message to display or an empty string.
A function that should return one of the FileReaderParser functions to start uploading a file to the browser.
The file to get a parser for
the FileReaderParser string.
A function that is used to determine if a TextField or TextArea is in an
errored state.
All the current options that can be used to determine the error state.
True if the component is considered to be in an errored state.
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.
The file being checked
A regex that will only be defined if the
extensions list had at least one value.
The list of extensions allowed
true if the file has a valid name.
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.
The next value that should be set for the listbox.
The option that was selected.
Part of the listbox props to help identify which listbox has been changed if reusing an event handler for multiple form parts.
An ordered list containing:
number value of the field which will be updated based on the
NumberFieldHookOptions.updateOnChange optionThese 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.
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.
The Checkbox component is just a wrapper for the InputToggle that
defaults to reasonable defaults for a checkbox input.
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.
This component is a wrapper for the <input type="file" /> that can be themed
like a button.
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.
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".
A wrapper component that can be used to display a TextField related
component or TextArea along with the FormMessage component.
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.
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.
This is a simple wrapper for the MenuItemInputToggle component to render it as a checkbox and pulling the checkbox icon from the IconProvider.
A wrapper for the <input type="file"> element that works within menus.
This is a low-level component that should probably not be used externally and
instead the MenuItemCheckbox, MenuItemRadio, or MenuItemSwitch should
be used instead.
This is a simple wrapper for the MenuItemInputToggle component to render it as a radio and pulling the radio icon from the IconProvider.
This is a simple wrapper for the MenuItemInputToggle component to render it as a switch.
This is a wrapper for the TextField component that can be used within
Menus by updating the onKeyDown and onClick behavior.
Note: This is not the TextFieldWithMessage since the message part is
hard to style nicely within menus. You'd most likely want to use another menu
for displaying errors.
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.
The Option component is a simple wrapper for the SimpleListItem that adds
some required a11y for behaving as the option role.
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".
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: Unlike the TextFieldWithMessage and TextAreaWithMessage, the error
icon will do nothing for this component unless the disableVisibility prop
is enabled.
The Radio component is just a wrapper for the InputToggle that
defaults to reasonable defaults for a radio input.
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.
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.
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.
The SliderContainer component is mostly an internal 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.
The slider thumb implements the role="slider" for the Slider and
RangeSlider components.
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.
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.
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}
/>
);
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.
This component is used to add an an icon before or after the text field with correct styling.
This is a container component that is used to structure the text field with different parts and themes.
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}
/>
);
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.
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:
getOptionLabel utilleftAddonleftAddon, use the TextIconSpacing of
the label + the icon or avatar.The option to get a display label for
The key to use to extract a label from the option when it is an object
Boolean if a leftAddon should be added with
TextIconSpacing to the result.
A renderable node to display in a Select field.
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.The base id of the listbox.
The current index of the option
a "unique" id for the option
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.
The option that should be converted into a renderable label element.
The object key to use to extract the label from an option object.
a renderable label to display.
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.
Since you'll normally want all of your form components to use the same theme, this is a simple way to provide the same theme to all components without needing all the prop-drilling/copying.
The default implementation for showing an error icon in TextField and
TextArea components that will only display when the error flag is enabled.
The default implementation for getting an error message for the TextField
or TextArea components that relies on the behavior of the
ChangeValidationBehavior
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.
This function will attempt to read:
<img>, <audio>, and <video> tagsArrayBuffer which can be manually converted into a
data url if needed with URL.createObjectURLThis util will split all the current upload stats by status.
The FileUploadStats list generally returned by the useFileUpload hook.
the SplitFileUploads.
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.
The file to check
true if the file should be considered as a audio content file.
A simple type-guard that can be used to check if the FileValidationError is the FileAccessError which can be useful when displaying the errors to the user.
The error to check
true if the error is a FileAccessError
A simple type-guard that can be used to check if the FileValidationError is the FileExtensionError which can be useful when displaying the errors to the user.
The error to check
true if the error is a FileExtensionError
A simple type-guard that can be used to check if the FileValidationError is the FileSizeError which can be useful when displaying the errors to the user.
The error to check
true if the error is a FileSizeError
A simple type-guard that can be used to check if the FileValidationError is the GenericFileError which can be useful when displaying the errors to the user.
The error to check
true if the error is a FileAccessError
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.
The file to check
true if the file should be considered as a text content file.
A type guard that simply checks if the option is considered an object of list item props.
The option to check
true if the option is considered a object of list item props and will ensure that the option is typed as ListboxOptionProps
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.
The file to check
true if the file matches an image, audio, or video file.
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.
The file to check
true if the file should be considered as a text-content file.
A simple type-guard that can be used to check if the FileValidationError is the TooManyFilesError which can be useful when displaying the errors to the user.
The error to check
true if the error is a TooManyFilesError
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.
The file to check
true if the file should be considered as a video content file.
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.
A small hook that can be used for controlling the state of a single Checkbox component.
Boolean if the input should be checked by default. Changing this value will not update the state after initial render.
An optional change event handler to also call when the checked state changes.
a list containing the checked state, a change event handler, and then a manual set checked action.
This hook can be used to control the state of a radio group or a select element.
The default value. If you want the user to specifically choose a value, set this to the empty string.
An optional change event handler to also call when the change event is triggered.
a list containing the current value, a change event handler, and then a manual value setter.
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.
An optional HTMLElement type that is used for the FileUploadHandlers.
An optional error type that gets returned from the FilesValidator.
All the FileUploadOptions
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" });
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.
The allowed values for the checkboxes
The allowed values for the checkboxes which is used to control the checked states.
an object containing the rootProps to pass to the indeterminate
checkbox, a getProps function to provide the controlled behavior for the
additional values in the checkbox list, a list of checkedValues, and a
setCheckedValues function to manually override the state if needed.
This hook is used to control the value for the TextField component acting
as an <input type="number"> and ensuring that a "valid" number is
available. There is also built-in support for using the validity
api/constraint validation so that real-time errors can be presented to the
user as they type along with the FormMessage component.
Simple example:
const [value, fieldProps] = useNumberField({
id: 'field-id',
min: 0,
max: 10,
defaultValue: 0,
disableMessage: true,
});
return <TextField {...fieldProps} label="Label" placeholder="0" />;
Step example and messaging:
const [value, fieldProps] = useNumberField({
id: 'field-id',
min: 0,
max: 10,
step: 2,
defaultValue: 0,
});
return <TextFieldWithMessage {...fieldProps} label="Label" placeholder="0" />;
All the options used to control the functionality of this hook.
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.
An optional default value to use. When omitted, this
will be the [min, max] values
An object containing the min and max values allowed for
the slider as well as a step to indicate valid values between the min and
max.
an ordered list containing the current value followed by the
RangeSlider props
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.
The default value to use
an ordered list containing the current value followed by the dispatch function to update the state.
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.
An optional default value to use for the slider. This
will default to the min option when undefined.
An object containing the min and max values allowed for
the slider as well as a step to indicate valid values between the min and
max.
an ordered list containing the current value followed by the
Slider props
This hook is used to control the value for a TextField or TextArea
component along with some simple validation checks using the browser validity
api/constraint validation. This also provides props that can be passed to the
FormMessage component to display error messages or help text.
Note: Even though this hook exists, it is highly recommended to use a form helper library like react-hook-form for more complex forms
All the options used to control the functionality of this hook.
A pretty decent default implementation for validating files with the useFileUpload that ensures the FilesValidationOptions are enforced before allowing a file to be uploaded.
The list of files to check
Generated using TypeDoc
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
changeevent phase. The validation message will always be shown on blur.When this is:
true-> always show the browser message when it existsfalse-> never show the browser message"recommended"-> only shows the browser message if it is not one of theRECOMMENDED_IGNORED_KEYSvalidation errorskeyof 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@since 2.5.0