TextField

Usage

• Use TextField for short, freeform text input such as names, email addresses, or single-line values.
• Use TextArea for longer, multi-line text such as descriptions or messages.
• Use JsonField for validated JSON input within a textarea.
• Use Search for search-specific input fields.
• Provide a visible label so users understand the purpose of the field at a glance. If a visible label is not possible, provide an ariaLabel.
• Never use placeholders in place of visible labels.

Types

• Text (type="text") — the default type for names, emails, and other short-form text.
• Password (type="password") — masks user input by default and includes a toggle button to show/hide the password.

Appearance

• Medium (size="md") — default size for most use cases.
• Small (size="sm") — use for dense layouts and smaller viewports.
• Add a leading icon (icon) to emphasize the visual meaning of the field, such as denoting search functionality. Set iconColor to control icon color (defaults to "subtle").

Behaviors

• Base, hover, focus, active — standard form control interaction states.
• Active state (isActive) — renders the field in an "active" styled state programmatically.
• Disabled state (isDisabled) — prevents all interaction; background and text adopt disabled styling.
• Loading state (isLoading) — displays a spinner inside the field to indicate a background operation.
• Danger state (isInvalid + error) — applies danger styling and displays an error message below the field. Setting error alone also triggers invalid styling.
• Clear button (isClearable + onClear) — adds a clear button that resets the field. The button is hidden when the field is empty or disabled.
• Password visibility toggle — automatically renders for type="password" fields. Disable with shouldShowPasswordVisibilityToggle={false}.

Customization

• Pass rich content (icons, tooltips, optional indicators) as the label prop value.
• Pass rich content (links, formatted text) as the description or error prop value.

Content

• Write clear, concise labels using nouns or noun phrases. Never use instructional phrases as labels.
• Use placeholders to show example text and formatting, not to repeat the label. Leave placeholders empty when no formatting hint is needed.
• Write description text as short, complete sentences that provide hints, formatting guidance, or constraints.
• Write error messages that describe the specific problem and how to resolve it. Never use vague errors like "Invalid input".

Implementation Notes

• isClearable requires onClear to render the clear button — both must be set.
• label, description, and error accept ReactNode in React for rich content directly as props.
• In Ember, use <PlumaTextField> with @argName syntax. Named blocks :label, :description, and :error allow custom rich content for those slots.
• shouldShowPasswordVisibilityToggle defaults to true for type="password" fields. Set to false to hide the toggle.
• unsafe_leftSectionComponent and unsafe_rightSectionComponent allow rendering custom components inside the input wrapper on the left or right side.
• unsafe_inputWrapperClassName allows applying additional classes to the input wrapper element.
• wrapperRef (React) and wrapperModifier (Ember) provide access to the input wrapper element.
• shouldAllowAutofill controls browser autofill and password manager integration. Defaults to false (autofill disabled). Set to true for fields where autofill is desired.
• Deprecated size values "medium" and "small" are remapped internally to "md" and "sm".