@versini/ui-textinput

Accessible and feature-rich React text input components built with TypeScript and TailwindCSS.

The TextInput package provides standard text inputs and masked text inputs with comprehensive form features including validation states, helper text, and customizable styling. Perfect for building accessible forms and user interfaces.

Table of Contents

• Features
• Installation
• Usage
• API

Features

• 🎯 Multiple Input Types: TextInput and TextInputMask components
• ♿ Accessible: WCAG compliant with proper labeling and keyboard navigation
• 🎨 Customizable: Multiple sizes, themes, and styling options
• 🔧 Form Integration: Built-in validation states and helper text
• 🌲 Tree-shakeable: Lightweight and optimized for bundle size
• 🔧 TypeScript: Fully typed with comprehensive prop definitions
• 🎭 Theme Support: Built-in support for light, dark, and system themes

Installation

npm install @versini/ui-textinput

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

Basic TextInput

import { TextInput } from "@versini/ui-textinput";

function App() {
  return (
    <TextInput
      label="Email Address"
      name="email"
      type="email"
      placeholder="Enter your email"
    />
  );
}

TextInput with Helper Text

import { TextInput } from "@versini/ui-textinput";

function App() {
  return (
    <TextInput
      label="Password"
      name="password"
      type="password"
      helperText="Must be at least 8 characters long"
      placeholder="Enter your password"
    />
  );
}

TextInput with Error State

import { TextInput } from "@versini/ui-textinput";

function App() {
  return (
    <TextInput
      label="Username"
      name="username"
      error
      helperText="Username is already taken"
      defaultValue="invalid-username"
    />
  );
}

TextInput with Right Element

import { TextInput } from "@versini/ui-textinput";
import { Button } from "@versini/ui-button";

function App() {
  return (
    <TextInput
      label="Search"
      name="search"
      placeholder="Search for anything..."
      rightElement={
        <Button size="small" variant="primary">
          Search
        </Button>
      }
    />
  );
}

TextInputMask (Password with Toggle)

import { TextInputMask } from "@versini/ui-textinput";
import { ButtonIcon } from "@versini/ui-button";
import { IconEye, IconEyeOff } from "@versini/ui-icons";
import { useState } from "react";

function App() {
  const [masked, setMasked] = useState(true);

  return (
    <TextInputMask
      label="Password"
      name="password"
      type={masked ? "password" : "text"}
      onMaskChange={setMasked}
      rightElement={
        <ButtonIcon
          label={masked ? "Show password" : "Hide password"}
          noBackground
        >
          {masked ? <IconEye /> : <IconEyeOff />}
        </ButtonIcon>
      }
    />
  );
}

API

TextInput Props

| Prop | Type | Default | Description | | --------------------- | ----------------------------------------------- | ---------- | -------------------------------------------------- | | label | string | - | The label of the TextInput (required) | | name | string | - | The name of the TextInput (required) | | rightElement | React.ReactElement | - | Element to render on the right side | | rightElementClassName | string | - | Extra classes for the right element container | | error | boolean | false | Whether the TextInput is in error state | | helperText | string | - | Text to add to the bottom of the TextInput | | size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | Controls input height and padding | | mode | "dark" \| "light" \| "system" \| "alt-system" | "system" | The mode of TextInput (controls color) | | focusMode | "dark" \| "light" \| "system" \| "alt-system" | "system" | The focus ring color mode | | labelHidden | boolean | false | Hides the label visually but retains accessibility | | labelId | string | - | Id to use for the TextInput label | | noBorder | boolean | false | Whether the TextInput has a border | | raw | boolean | false | Whether to render with styles | | inputClassName | string | - | CSS class(es) for the actual input element |

Also supports all standard HTML input element attributes

TextInputMask Props

| Prop | Type | Default | Description | | ------------------- | --------------------------- | ------- | ---------------------------------------------- | | rightElement | React.ReactElement | - | Element to render on the right side (required) | | onMaskChange | (masked: boolean) => void | - | Callback fired when mask state changes | | onTextInputMaskBlur | () => void | - | Callback fired when user blurs out |

Also supports all TextInput props except rightElement is required

Examples

Form with Validation

import { TextInput } from "@versini/ui-textinput";
import { Button } from "@versini/ui-button";
import { useState } from "react";

function ValidationForm() {
  const [errors, setErrors] = useState({});
  const [values, setValues] = useState({
    email: "",
    password: "",
    confirmPassword: ""
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    // Validation logic here
  };

  return (
    <form onSubmit={handleSubmit} className="space-y-4 max-w-md">
      <TextInput
        label="Email"
        name="email"
        type="email"
        value={values.email}
        onChange={(e) => setValues({ ...values, email: e.target.value })}
        error={!!errors.email}
        helperText={errors.email || "We'll never share your email"}
        required
      />

      <TextInput
        label="Password"
        name="password"
        type="password"
        value={values.password}
        onChange={(e) => setValues({ ...values, password: e.target.value })}
        error={!!errors.password}
        helperText={errors.password || "Must be at least 8 characters"}
        required
      />

      <TextInput
        label="Confirm Password"
        name="confirmPassword"
        type="password"
        value={values.confirmPassword}
        onChange={(e) =>
          setValues({ ...values, confirmPassword: e.target.value })
        }
        error={!!errors.confirmPassword}
        helperText={errors.confirmPassword}
        required
      />

      <Button type="submit" fullWidth>
        Create Account
      </Button>
    </form>
  );
}

Different Sizes

import { TextInput } from "@versini/ui-textinput";

function SizeExamples() {
  return (
    <div className="space-y-4">
      <TextInput
        label="Extra Small"
        name="xs"
        size="xs"
        placeholder="Extra small input"
      />
      <TextInput label="Small" name="sm" size="sm" placeholder="Small input" />
      <TextInput
        label="Medium"
        name="md"
        size="md"
        placeholder="Medium input (default)"
      />
      <TextInput label="Large" name="lg" size="lg" placeholder="Large input" />
      <TextInput
        label="Extra Large"
        name="xl"
        size="xl"
        placeholder="Extra large input"
      />
    </div>
  );
}

Search Input with Icon

import { TextInput } from "@versini/ui-textinput";
import { ButtonIcon } from "@versini/ui-button";
import { IconSearch } from "@versini/ui-icons";

function SearchInput() {
  return (
    <TextInput
      label="Search Products"
      name="search"
      placeholder="Search for products..."
      rightElement={
        <ButtonIcon label="Search" variant="primary" size="small" noBackground>
          <IconSearch />
        </ButtonIcon>
      }
      rightElementClassName="mr-2"
    />
  );
}

Clearable Input

import { TextInput } from "@versini/ui-textinput";
import { ButtonIcon } from "@versini/ui-button";
import { IconClose } from "@versini/ui-icons";
import { useState } from "react";

function ClearableInput() {
  const [value, setValue] = useState("");

  return (
    <TextInput
      label="Search Query"
      name="query"
      value={value}
      onChange={(e) => setValue(e.target.value)}
      placeholder="Type to search..."
      rightElement={
        value ? (
          <ButtonIcon label="Clear" noBackground onClick={() => setValue("")}>
            <IconClose />
          </ButtonIcon>
        ) : undefined
      }
    />
  );
}

Password Input with Strength Indicator

import { TextInputMask } from "@versini/ui-textinput";
import { ButtonIcon } from "@versini/ui-button";
import { IconEye, IconEyeOff } from "@versini/ui-icons";
import { useState } from "react";

function PasswordWithStrength() {
  const [password, setPassword] = useState("");
  const [masked, setMasked] = useState(true);

  const getPasswordStrength = (password) => {
    // Simple strength calculation
    let strength = 0;
    if (password.length >= 8) strength++;
    if (/[A-Z]/.test(password)) strength++;
    if (/[0-9]/.test(password)) strength++;
    if (/[^A-Za-z0-9]/.test(password)) strength++;
    return strength;
  };

  const strength = getPasswordStrength(password);
  const strengthColors = ["red", "orange", "yellow", "green"];
  const strengthLabels = ["Weak", "Fair", "Good", "Strong"];

  return (
    <div className="space-y-2">
      <TextInputMask
        label="Password"
        name="password"
        type={masked ? "password" : "text"}
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        onMaskChange={setMasked}
        rightElement={
          <ButtonIcon
            label={masked ? "Show password" : "Hide password"}
            noBackground
          >
            {masked ? <IconEye /> : <IconEyeOff />}
          </ButtonIcon>
        }
      />

      {password && (
        <div className="space-y-1">
          <div className="flex space-x-1">
            {[...Array(4)].map((_, i) => (
              <div
                key={i}
                className={`h-1 flex-1 rounded ${
                  i < strength
                    ? `bg-${strengthColors[strength - 1]}-500`
                    : "bg-gray-200"
                }`}
              />
            ))}
          </div>
          <p className="text-sm text-gray-600">
            Password strength: {strengthLabels[strength - 1] || "Too weak"}
          </p>
        </div>
      )}
    </div>
  );
}

Theme Variations

import { TextInput } from "@versini/ui-textinput";

function ThemeVariations() {
  return (
    <div className="space-y-4">
      <TextInput
        label="Light Theme"
        name="light"
        mode="light"
        placeholder="Light theme input"
      />

      <TextInput
        label="Dark Theme"
        name="dark"
        mode="dark"
        placeholder="Dark theme input"
      />

      <TextInput
        label="System Theme"
        name="system"
        mode="system"
        placeholder="System theme input"
      />
    </div>
  );
}