HeadsUp UI

A modern, accessible React form components library with built-in validation support.

Features

• 🎨 Modern Design: Clean, responsive components with customizable styling
• 🧩 Composable: Components work together seamlessly but can be used independently
• 📱 Responsive: Mobile-friendly with appropriate keyboard types
• ♿ Accessible: Built with accessibility in mind, including keyboard navigation and ARIA support
• 🔄 Flexible State Management: Works with React useState, Redux, or your own state solution
• 🧮 Validation Support: Easy integration with validation libraries like @sk2you/schema-validator
• 📝 Form Structure: Support for nested objects and arrays in form data
• 🌓 Customizable: Theming through Tailwind CSS with class name overrides

Installation

npm install headsup-ui

# Peer dependencies
npm install react react-dom
npm install clsx tailwind-merge lucide-react

Components

• CustomInput: Text, email, password, number inputs with various features
• CustomTextarea: Multiline text input with character counting
• CustomCheckbox: Boolean input with label support
• CustomRadio: Radio button for selecting from options
• CustomSwitch: Toggle switch for boolean settings

Basic Usage

import React, { useState } from 'react';
import { 
  CustomInput, 
  CustomTextarea, 
  CustomCheckbox, 
  CustomRadio, 
  CustomSwitch 
} from 'headsup-ui';

function MyForm() {
  const [formValues, setFormValues] = useState({
    name: '',
    email: '',
    message: '',
    agreeToTerms: false,
    contactMethod: '',
    notifications: true
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    console.log(formValues);
  };

  return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <CustomInput
        name="name"
        label="Full Name"
        placeholder="John Doe"
        values={formValues}
        setValues={setFormValues}
        clearable
      />
      
      <CustomInput
        name="email"
        label="Email Address"
        type="email"
        placeholder="[email protected]"
        values={formValues}
        setValues={setFormValues}
        caseSensitive={false}
        clearable
      />
      
      <CustomTextarea
        name="message"
        label="Your Message"
        rows={5}
        placeholder="Type your message here..."
        values={formValues}
        setValues={setFormValues}
        maxLength={500}
        showCounter
      />
      
      <div className="space-y-2">
        <h3 className="text-sm font-medium">Preferred Contact Method</h3>
        <CustomRadio
          name="contactMethod"
          label="Email"
          value="email"
          values={formValues}
          setValues={setFormValues}
        />
        <CustomRadio
          name="contactMethod"
          label="Phone"
          value="phone"
          values={formValues}
          setValues={setFormValues}
        />
      </div>
      
      <CustomSwitch
        name="notifications"
        label="Enable Notifications"
        values={formValues}
        setValues={setFormValues}
      />
      
      <CustomCheckbox
        name="agreeToTerms"
        label="I agree to the Terms and Conditions"
        values={formValues}
        setValues={setFormValues}
      />
      
      <button type="submit" className="px-4 py-2 bg-blue-600 text-white rounded">
        Submit
      </button>
    </form>
  );
}

Advanced Usage

Nested Objects

const [formValues, setFormValues] = useState({
  profile: {
    firstName: '',
    lastName: '',
    bio: ''
  }
});

// In your JSX:
<CustomInput
  name="firstName"
  parent="profile"
  label="First Name"
  values={formValues}
  setValues={setFormValues}
/>

Array Fields

const [formValues, setFormValues] = useState({
  addresses: [
    { street: '', city: '', zipCode: '' },
    { street: '', city: '', zipCode: '' }
  ]
});

// In your JSX:
<CustomInput
  name="street"
  parent="addresses"
  index={0}
  label="Street (Home)"
  values={formValues}
  setValues={setFormValues}
/>

<CustomInput
  name="street"
  parent="addresses"
  index={1}
  label="Street (Work)"
  values={formValues}
  setValues={setFormValues}
/>

Redux Integration

import { useDispatch, useSelector } from 'react-redux';
import { updateFormData } from './formSlice';

function ReduxForm() {
  const dispatch = useDispatch();
  const formValues = useSelector(state => state.form.data);

  return (
    <CustomInput
      name="username"
      label="Username"
      values={formValues}
      setValues={updateFormData}
      useRedux={true}
      dispatch={dispatch}
    />
  );
}

Form Validation with @sk2you/schema-validator

import { validationSchema, useValidation } from '@sk2you/schema-validator';

// Define validation schema
const formSchema = {
  username: validationSchema.string()
    .required('Username is required')
    .min(3, 'Username must be at least 3 characters'),
  
  email: validationSchema.string()
    .required('Email is required')
    .regex(
      /^[a-zA-Z0-9](?:[a-zA-Z0-9._%+-]*[a-zA-Z0-9])?@[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?(?:\.[a-zA-Z]{2,})+$/, 
      'Invalid email format'
    ),
  
  password: validationSchema.string()
    .required('Password is required')
    .min(8, 'Password must be at least 8 characters')
};

// In your component
const { errors, validate, validateAll } = useValidation(formSchema);

// In your JSX
<CustomInput
  name="username"
  label="Username"
  values={formValues}
  setValues={setFormValues}
  error={errors}
  validate={validate}
  caseSensitive={false}
/>

// On form submission
const handleSubmit = (e) => {
  e.preventDefault();
  const isValid = validateAll(formValues);
  if (isValid) {
    console.log('Form is valid:', formValues);
    // Submit form data
  }
};

Custom Styling

<CustomInput
  name="email"
  label="Email Address"
  values={formValues}
  setValues={setFormValues}
  // Override specific class names
  overrideClass={{
    labelClassName: 'text-purple-700 font-bold',
    inputClassName: 'bg-purple-50 border-purple-300 focus:border-purple-500',
    helperClassName: 'text-purple-500 italic'
  }}
/>

API Reference

CustomInput

| Prop | Type | Default | Description | |------|------|---------|-------------| | name | string | (required) | Field name | | label | string | undefined | Label text | | type | string | 'text' | Input type (text, email, password, etc.) | | keyboardType | string | undefined | Mobile keyboard type | | values | object | {} | Form values object | | setValues | function | (required) | Function to update form values | | parent | string | undefined | Parent object for nested fields | | index | number | undefined | Array index for array fields | | useRedux | boolean | false | Whether to use Redux | | dispatch | function | undefined | Redux dispatch function | | helperText | string | undefined | Helper text displayed below input | | error | object | undefined | Error object from validation | | errorText | string | undefined | Error text to display | | placeholder | string | undefined | Input placeholder | | clearable | boolean | false | Whether input should have a clear button | | showCounter | boolean | false | Whether to show character counter | | maxLength | number | undefined | Maximum input length | | disabled | boolean | false | Whether input is disabled | | className | string | '' | Additional CSS class | | onChange | function | undefined | Additional onChange handler | | validate | function | undefined | Validation function | | caseSensitive | boolean | true | Whether input should be case-sensitive | | overrideClass | object | {} | Class name overrides |

CustomTextarea

Similar to CustomInput with additional properties:

| Prop | Type | Default | Description | |------|------|---------|-------------| | rows | number | 4 | Number of visible text rows |

CustomCheckbox

Similar to CustomInput but specifically for boolean values.

CustomRadio

Similar to CustomInput with additional properties:

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | string | (required) | Radio button value |

CustomSwitch

Similar to CustomCheckbox but with a toggle switch UI.

Styling with Tailwind CSS

HeadsUp UI components are built with Tailwind CSS. To customize the appearance, you can:

1. Override specific class names using the overrideClass prop
2. Use the className prop to add additional classes to the container
3. Configure your Tailwind theme in tailwind.config.js to change colors, sizes, etc.

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          // ...
          600: '#0284c7',
          // ...
        },
      },
    },
  },
}

TypeScript Support

HeadsUp UI is built with TypeScript and includes type definitions for all components and props.

import { CustomInputProps } from 'headsup-ui';

// Use types directly
const MyInput: React.FC<Omit<CustomInputProps, 'values' | 'setValues'>> = (props) => {
  // Implementation
};

Browser Support

HeadsUp UI supports all modern browsers, including:

• Chrome (and Chromium-based browsers like Edge)
• Firefox
• Safari
• Mobile browsers on iOS and Android

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

HeadsUp UI is developed and maintained by [Your Name/Company].

Special thanks to:

• Tailwind CSS
• Lucide Icons
• clsx
• tailwind-merge