CatalystTextFieldv2.1.2Documentation Under Review
A versatile single-line text input component with icon slots, tag support, and validation states optimized for product interfaces.
Overview
The Product TextField component provides a flexible, single-line text input optimized for product interfaces. It features a slot-based architecture for icons and tags, multiple input types, validation states, and product-specific typography scaling.
Installation
npm install @pmi/catalyst-text-fieldUsage
Basic TextField
Variants
Sizes
The Product TextField component supports three size variants with product-optimized icon scaling.
States
Danger State
Use the danger prop to indicate validation errors or warning states.
Disabled State
The disabled state prevents user interaction and reduces opacity.
Sizes
The Product TextField supports three size variants with product-optimized typography: sm, md (default), and lg.
States
Danger State
Use the danger prop to indicate validation errors or warning states.
Disabled State
The disabled state prevents user interaction and reduces opacity to 40%.
All States
Advanced Examples
Character Counter with Validation
Real-time character counting with validation feedback for admin interfaces.
Character Limit Reached
TextField with character limit already reached, showing error state with validation feedback.
With Helper Text
TextField with informative helper text below the input for user guidance.
Tag Input for Categories
Use tags inside text fields for category management and filtering.
Password Field with Toggle
Security-focused password input with show/hide functionality.
Real-World Examples
Custom Styling
Payment Field
Credit card input with payment method selection and automatic formatting.
File Upload Field
File input with validation, preview, and clear functionality.
Phone Number Field
International phone number input with country selection and validation.
Accessibility
The Product TextField component follows WCAG 2.1 AA guidelines:
- Semantic HTML: Uses native
<input>element for proper form integration - ARIA Labels: Associate with
<Label>component usinghtmlForandidattributes - ARIA Descriptions: Use
aria-describedbyto connect with helper text or error messages - ARIA Invalid: Set
aria-invalid="true"when in danger/error state - Role Alert: Use
role="alert"on error messages for immediate screen reader announcement - Focus Management: Clear focus indicators with 1px inset ring meeting contrast requirements
- Keyboard Navigation: Full keyboard support with standard input interactions
- Input Types: Proper
typeattributes optimize mobile keyboards and browser behavior - Screen Reader Labels: Use
.sr-onlyfor icon-only content (e.g., "Error:")
API Reference
TextFieldRoot Props
| Prop | Type | Default | Description |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | 'md' | Controls height and typography scale (compact/standard/emphasized) |
danger | boolean | false | Applies error/warning styling with red color scheme |
disabled | boolean | false | Disables the text field and reduces opacity to 40% |
unstyled | boolean | false | Disables all default CVA/Tailwind styling, only applies className. |
asChild | boolean | false | Enables composition by merging props onto child element |
className | string | - | Additional CSS classes for custom styling |
TextFieldInput Props
| Prop | Type | Default | Description |
|---|---|---|---|
type | 'text' | 'email' | 'password' | 'search' | 'tel' | 'url' | 'number' | 'date' | 'time' | 'month' | 'week' | 'datetime-local' | 'text' | HTML input type for different input behaviors and mobile keyboards |
placeholder | string | - | Placeholder text when input is empty |
value | string | - | Controlled value for state management |
defaultValue | string | - | Initial uncontrolled value |
onChange | (e: ChangeEvent<HTMLInputElement>) => void | - | Change event handler |
disabled | boolean | false | Disables the input |
maxLength | number | - | Maximum character limit (enforced by browser) |
minLength | number | - | Minimum character limit for validation |
required | boolean | false | Marks the field as required |
aria-label | string | - | Accessible label for screen readers |
aria-describedby | string | - | ID of element describing the input |
aria-invalid | boolean | 'true' | 'false' | - | Indicates validation state |
aria-required | boolean | 'true' | 'false' | - | Indicates if field is required |
unstyled | boolean | false | Disables all default CVA/Tailwind styling, only applies className. |
asChild | boolean | false | Enables composition by merging props onto child element |
TextFieldSlot Props
| Prop | Type | Default | Description |
|---|---|---|---|
side | 'left' | 'right' | - | Position of the slot within the text field |
asChild | boolean | false | Enables composition by merging props onto child element |
unstyled | boolean | false | Disables all default CVA/Tailwind styling, only applies className. |
className | string | - | Additional CSS classes for custom styling |
Related Components
- Label - For labeling form fields (shared component)
- SubText - For helper text and validation messages (shared component)
- TextArea - For multi-line text input
- Button - For interactive controls within slots
- Tag - For tag chip patterns
Best Practices
- Label Association: Always associate TextField with a Label using
htmlFor/id - Input Types: Use appropriate
typeattributes for better mobile keyboards and validation - Icon Sizing: Use xs/sm/md for sm/md/lg sizes respectively (product-specific scaling)
- Validation Timing: Provide immediate feedback on form submission, clear errors on input change
- Placeholder Text: Keep placeholder text concise and action-oriented for product interfaces
- Character Limits: Show character counters when enforcing
maxLengthfor user guidance - Helper Text: Use SubText to provide context for technical or admin-specific fields
- Password Security: Always include show/hide toggle and strength indicators where applicable
- Error Specificity: Make error messages specific and actionable for technical users
- Loading States: Disable and show loading feedback during API operations
- Monospace Font: Use
font-monofor code, API keys, and technical identifiers - Dense Layouts: Use
smsize for compact admin interfaces and data grids