MUITextField
MUITextField extends the Material UI
TextField component, accepting
almost all of its props while wiring up the label, error state and helper text
for you. It is a controlled component that works with plain useState or any
form library able to provide a value and receive changes.
For specialized inputs, you can also use MUIPasswordInput for password values, MUINumberInput for numeric input.
For multiline input, use MUITextArea instead of
setting multiline on MUITextField. It grows with its content, and adds
maxChars to cap the length, with an optional current/max character counter
(showCharLimit, renderCharLimit).
Usage
import MUITextField, { MUITextFieldProps } from '@nish1896/mui-components/mui/textfield';Provide fieldName, value and onValueChange to render a fully functional
text field:
const [firstName, setFirstName] = useState();
<MUITextField
fieldName="firstName"
value={firstName}
onValueChange={({ newValue, event }) => setFirstName(newValue)}
/>onValueChange receives { newValue, event }: the typed string and the change
event.
Validation stays in your hands — derive errorMessage from your own state or
form library and the field renders in an error state:
<MUITextField
fieldName="email"
value={email}
onValueChange={({ newValue }) => setEmail(newValue)}
onBlur={() => setEmailError(validateEmail(email))}
errorMessage={emailError}
/>Customizing the label
The label defaults to one generated from fieldName, so firstName becomes
"First Name". Use label to override it with any ReactNode. required
appends the required marker.
showLabelAboveFormField renders the label above the input instead of inside
it, and hideLabel removes the visible label while keeping an accessible one.
formLabelProps is forwarded to the label, for example to style it with sx.
<MUITextField
fieldName="email"
label="Work email"
required
showLabelAboveFormField
formLabelProps={{
sx: { fontWeight: 600 }
}}
helperText="We never share your email"
formHelperTextProps={{
sx: { fontStyle: 'italic' }
}}
value={email}
onValueChange={({ newValue }) => setEmail(newValue)}
/>To place every label above its field at once, use allLabelsAboveFields in
ConfigProvider.
Validation
MUITextField doesn't validate on its own. You apply the rules you need, such
as a minimum or maximum length or a specific pattern, in your own code or form
library, and pass the resulting message to errorMessage. The field then
switches to an error state and shows the message below the input. The examples
below show the common patterns.
Using a regex
Run your rule on newValue and keep the message in state, so the field shows
the error as the user types:
const [username, setUsername] = useState('');
const [usernameError, setUsernameError] = useState<string>();
<MUITextField
fieldName="username"
value={username}
onValueChange={({ newValue }) => {
setUsername(newValue);
setUsernameError(
/^[a-z0-9_]{3,16}$/.test(newValue)
? undefined
: 'Use 3-16 lowercase letters, digits or underscores'
);
}}
errorMessage={usernameError}
/>To block invalid characters instead of reporting them, only update the state
when newValue passes the check:
onValueChange={({ newValue }) => {
if (/^\d*$/.test(newValue)) setZip(newValue);
}}Showing multiple errors
errorMessage also accepts a string[]. Every message is shown together, which
suits a field that can fail several rules at once. renderError receives the
same list as errors and can render it your way, and hideErrorMessage keeps
the error state without showing any text.
const errors = [
!/[A-Z]/.test(value) && 'Add an uppercase letter',
!/\d/.test(value) && 'Add a digit',
value.length < 8 && 'Use at least 8 characters'
].filter(Boolean) as string[];
<MUITextField
fieldName="handle"
value={value}
onValueChange={({ newValue }) => setValue(newValue)}
errorMessage={errors}
renderError={errors => (
<ul style={{ margin: 0, paddingLeft: 16 }}>
{errors.map(error => <li key={error}>{error}</li>)}
</ul>
)}
/>An empty string or an empty array clears the error. helperText is shown while
there is no visible error.
API
MUITextFieldProps also accepts the remaining
TextFieldProps
in addition to the props below.
Props marked with * are required.
| Name | Type | Description |
|---|---|---|
fieldName* | string | Name/path of the field. Used to derive the id, the default label, and the name attribute. This prop is required for all components. |
value | string | null | Current value of the field. This is a controlled component — value and onValueChange must be supplied together, typically backed by your own state or form library. undefined/null are treated as an empty string. |
onValueChange* | ({ newValue, event }) => void | Called on every input change with the next string value and the original change event. Call your state setter (or form library's setter) with newValue to update value. |
label | ReactNode | Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name". |
showLabelAboveFormField | boolean | When true, renders the field label above the form field in the FormLabel component, instead of inside or beside it. Takes precedence over allLabelsAboveFields from the ConfigProvider, so false keeps the label inside this field even when the config places every label above its field. |
formLabelProps | FormLabelProps | FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
hideLabel | boolean | When true, hides the rendered field label while preserving accessible labeling where possible. |
required | boolean | Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes. |
errorMessage | string | string[] | Validation error for the field — pass a single message string, or a string[] when the field can fail multiple rules at once (every message is shown together). A non-empty string or array puts the field in an error state; undefined/''/[] clear it.Normalize your form library's error shape to this at the call site (e.g. an RHF FieldError via its .message). Use renderError to customize how the message(s) are rendered. |
renderError | (errors: string[]) => ReactNode | Custom renderer for the resolved error message(s), called only when the field is in an error state. Always receives a string[] — use errors[0] for the common single-message case, or map over errors when a field fails several rules. By default a single message renders as text and multiple messages render on separate lines. |
hideErrorMessage | boolean | If true, hides the error message text while keeping the field in an error state. |
helperText | ReactNode | Content displayed in the FormHelperText component below the field when there is no visible validation error. |
formHelperTextProps | FormHelperTextProps | FormHelperTextProps forwarded to the internal FormHelperText. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
customIds | { field, label, helperText, error } | Overrides the default field, label, helper text, and error IDs used for accessibility. |
Playground
Basic Input field with required, min & max length validation
Input with variant prop, and value transformation
Input with pattern validation, label above form-field, custom ids and renderError
Form State - Values & Errors
Reference
Source Code
View the full implementation of this component on GitHub.