FormInput

Overview

The FormInput component provides a comprehensive form input system that combines labels, descriptions, and validation states. It's designed to create accessible, user-friendly forms with proper labeling, helpful context, and clear validation feedback while maintaining consistency with the design system.

Usage

import { FormInput } from "@unkey/ui";
 
export default function MyComponent() {
  return (
    <FormInput
      label="Email Address"
      description="We'll use this to send you important updates."
      placeholder="Enter your email"
      required
    />
  );
}

Examples

Default FormInput

The default FormInput includes a label and optional description text, providing clear context for users.

1
2
3
4
5

<FormInput
  label="Username"
  description="Choose a unique username for your account"
  placeholder="e.g. gandalf_grey"
/>

Required Field

Use the required prop to indicate mandatory fields. This automatically adds a "Required" tag to the label.

1
2
3
4
5
6

<FormInput
  label="Email Address"
  description="We'll send your confirmation email here"
  required
  placeholder="frodo@shire.me"
/>

Required Field with Error

When a required field has an error, the "Required" tag changes to error styling to draw more attention.

1
2
3
4
5
6

<FormInput
  label="Username"
  required
  error="This username is already taken"
  placeholder="e.g. aragorn_king"
/>

Optional Field

Use the optional prop to explicitly indicate non-mandatory fields. This adds an "Optional" tag to the label.

1
2
3
4
5
6

<FormInput
  label="Phone Number"
  description="We'll only use this for important account notifications"
  optional
  placeholder="+1 (555) 123-4567"
/>

Success State

Indicates successful validation or acceptance of input value. The success icon and text provide positive feedback.

1
2
3
4
5
6
7

<FormInput
  label="API Key"
  description="Your API key has been verified"
  variant="success"
  defaultValue="sk_live_middleearth123"
  placeholder="Enter your API key"
/>

Warning State

Used for potentially problematic inputs that don't prevent form submission. Includes a warning icon and explanatory text.

1
2
3
4
5
6
7

<FormInput
  label="Password"
  description="Your password is about to expire"
  variant="warning"
  type="password"
  placeholder="Enter your password"
/>

Error State

Shows validation errors or other issues that need user attention. Features prominent error styling and message.

1
2
3
4
5

<FormInput
  label="Repository Name"
  error="A repository with this name already exists"
  placeholder="my-awesome-project"
/>

Disabled State

Apply when the field should be non-interactive, such as during form submission or based on other field values.

1
2
3
4
5
6

<FormInput
  label="Project Name"
  description="Name of your new project"
  defaultValue="The Fellowship Project"
  placeholder="Enter project name"
/>

With Default Value

Pre-populated input with an initial value that users can modify.

1
2
3
4
5
6

<FormInput
  label="Project Name"
  description="Name of your new project"
  defaultValue="The Fellowship Project"
  placeholder="Enter project name"
/>

Read-only State

For displaying non-editable information while maintaining form layout consistency.

1
2
3
4
5
6
7

<FormInput
  label="Generated Token"
  description="Copy this token for your records"
  readOnly
  defaultValue="tkn_1ring2rulethemall"
  placeholder="Your token will appear here"
/>

Complex Usage

Example of a FormInput with multiple props configured for a specific use case.

1
2
3
4
5
6
7
8

<FormInput
  label="Webhook URL"
  description="Enter the URL where we'll send event notifications"
  required
  placeholder="https://api.yourdomain.com/webhooks"
  className="max-w-lg"
  id="webhook-url-input"
/>

Features

• Built-in Labeling: Automatic label association with proper accessibility
• Description Support: Optional helper text for additional context
• Validation States: Multiple states (success, warning, error) with appropriate styling
• Required/Optional Indicators: Clear visual indicators for field requirements
• Accessibility: Full accessibility support with proper ARIA attributes
• Responsive Design: Adapts to different screen sizes
• Dark Mode Support: Consistent appearance in light and dark themes
• Customizable: Extensive styling options through className props

Props

The FormInput component extends the standard Input component props with additional form-specific properties:

Variants

Default

• Standard form input with label and optional description
• Use for most form fields
• Balanced visual weight and accessibility

Required

• Includes "Required" indicator for mandatory fields
• Use for fields that must be completed
• Clear visual indication of importance

Optional

• Includes "Optional" indicator for non-mandatory fields
• Use for fields that can be left empty
• Provides clarity in forms with mixed requirements

Success

• Green styling for positive validation states
• Use for successfully validated inputs
• Encourages positive user feedback

Warning

• Yellow/orange styling for cautionary states
• Use for inputs that need attention but aren't errors
• Indicates potential issues

Error

• Red styling for validation errors
• Use for failed validation or critical issues
• Clearly indicates problems that need resolution

Structure

The FormInput component is composed of:

1. Label Container - Contains the label text and required/optional indicators
2. Input Element - The actual input field with validation states
3. Description Text - Optional helper text below the input
4. Error Message - Validation error display when applicable
5. Status Icons - Visual indicators for different states

Styling

The component includes default styling with:

• Consistent spacing and typography from design system
• Color-coded validation states for semantic meaning
• Proper label positioning and association
• Dark mode support with appropriate color schemes
• Focus states for accessibility
• Customizable through className props

Custom Styling

You can customize the appearance using className props:

<FormInput
  label="Custom Input"
  description="Custom description"
  className="custom-form-input-class"
  variant="success"
/>

Accessibility

The FormInput component is built with accessibility in mind:

• Label Association: Labels are properly associated with inputs using htmlFor/id
• Error Announcements: Error messages are announced to screen readers using role="alert"
• Required Indicators: Required fields are marked both visually and via aria-required
• Helper Text: Helper text is linked to inputs using aria-describedby
• Validation States: Error states are indicated using aria-invalid
• Screen Reader Support: Announces validation states and requirements appropriately
• Keyboard Navigation: Full keyboard support for all interactions