MUIPasswordInput
MUIPasswordInput is a
TextField-based password field
with a built-in show/hide visibility toggle. It handles the label, error state
and helper text, and stays a plain controlled component.
Usage
import MUIPasswordInput, { MUIPasswordInputProps } from '@nish1896/mui-components/mui/password-input';MUIPasswordInput is a controlled input: pass fieldName, value and
onValueChange, and it handles the rest.
- A show/hide button at the end of the field swaps the input
typebetweenpasswordandtext. It is a real button, so it works from the keyboard, and clicking it doesn't take focus away from the input. - The button's accessible name switches between "Show password" and "Hide password".
autoCompletedefaults tooff. Set it tocurrent-passwordon a login form, ornew-passwordwhen creating or changing a password, so password managers can fill or offer to save it.
const [password, setPassword] = useState<string | undefined>();
<MUIPasswordInput
fieldName="password"
value={password}
onValueChange={({ newValue, event }) => setPassword(newValue)}
/>onValueChange receives { newValue, event }: the typed string and the change
event.
The sections below show how to customize the button with showPasswordIcon,
hidePasswordIcon and iconButtonProps.
Custom show/hide icons
showPasswordIcon is displayed while the password is hidden (clicking it
reveals the value), and hidePasswordIcon while it is visible (clicking it
hides the value). They default to the Material Visibility and VisibilityOff
icons, and accept any ReactNode:
import KeyIcon from '@mui/icons-material/Key';
import KeyOffIcon from '@mui/icons-material/KeyOff';
<MUIPasswordInput
fieldName="password"
value={password}
onValueChange={({ newValue }) => setPassword(newValue)}
showPasswordIcon={<KeyIcon />}
hidePasswordIcon={<KeyOffIcon />}
/>Plain text works too. Give the button a rounded-rectangle shape so the text fits:
<MUIPasswordInput
fieldName="password"
value={password}
onValueChange={({ newValue }) => setPassword(newValue)}
showPasswordIcon="Show"
hidePasswordIcon="Hide"
iconButtonProps={{
sx: {
borderRadius: 1,
px: 1.5,
fontSize: 14
}
}}
/>Styling the toggle button
iconButtonProps forwards
IconButtonProps to the toggle,
for example a size, color or sx:
<MUIPasswordInput
fieldName="password"
value={password}
onValueChange={({ newValue }) => setPassword(newValue)}
iconButtonProps={{
size: 'small',
color: 'warning',
sx: { '&:hover': { bgcolor: 'action.selected' } }
}}
/>type, onClick, onMouseDown, edge, disabled and aria-label are
controlled by the component, so overriding them has no effect. In particular:
- There is no callback for the visibility change, since
onClickcan't be replaced. - The accessible name is fixed to "Show password" / "Hide password".
Adding your own end adornment
An end adornment passed through slotProps.input is rendered before the toggle,
so both stay in the field:
import InputAdornment from '@mui/material/InputAdornment';
import LockIcon from '@mui/icons-material/Lock';
<MUIPasswordInput
fieldName="password"
value={password}
onValueChange={({ newValue }) => setPassword(newValue)}
slotProps={{
input: {
endAdornment: (
<InputAdornment position="end">
<LockIcon fontSize="small" />
</InputAdornment>
)
}
}}
/>Read-only and disabled
With readOnly, the value can't be edited but the toggle still works, so
the user can reveal it to verify it. disabled makes the whole field inert,
including the toggle.
API
MUIPasswordInputProps also accepts the remaining
TextFieldProps (variant,
placeholder, slotProps, sx) except type, multiline and rows.
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. |
showPasswordIcon | ReactNode | Custom icon displayed when the password is currently hidden. Clicking it reveals the password value. Default: <VisibilityIcon /> |
hidePasswordIcon | ReactNode | Custom icon displayed when the password is currently visible. Clicking it hides the password value. Default: <VisibilityOffIcon /> |
iconButtonProps | IconButtonProps | IconButtonProps forwarded to the internal show/hide toggle IconButton — custom size, sx, etc. The interaction/accessibility essentials (type, onClick, onMouseDown, edge, disabled, aria-label) are controlled by the component.Added in v2. |
readOnly | boolean | When true, the value is displayed but cannot be edited. Unlike disabled, the field stays focusable, and the show/hide toggle remains usable — a read-only value is meaningful, so the user can still reveal it to verify it. |
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
Integrated with TanStack Form — the password
field runs several rules at once (renderError lists them), a confirm field
validates against another field, and there are custom show/hide icons.
Reference
Source Code
View the full implementation of this component on GitHub.