headsup-ui

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="[e-mail]"
        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:

• Override specific class names using the overrideClass prop
• Use the className prop to add additional classes to the container
• 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