npm package: @formalia/react
Description: React headless SDK for Formalia - components, hooks, and utilities for form management, analytics, and submissions
Latest version: 0.1.51

# @formalia/react

React headless SDK for Formalia - components, hooks, and utilities for form management, analytics, and submissions.

## Features

-   🎨 **Dual API**: Styled components for quick start, headless for custom designs
-   🔧 **Framework Agnostic**: Works with any CSS framework or custom styles
-   🎯 **TypeScript First**: Full type safety and IntelliSense support
-   📱 **React 17+ Compatible**: Works with React 17, 18, and 19
-   🚀 **Zero Dependencies**: No required peer dependencies except React
-   🎨 **CSS Variables**: Easy theming and customization

## Installation

```bash
npm install @formalia/react
# or
pnpm add @formalia/react
# or
yarn add @formalia/react
```

## Quick Start

### Option 1: Styled Components (Recommended for rapid prototyping)

```tsx
import { Button, Input, FormProvider } from '@formalia/react';
import '@formalia/react/styles'; // Import pre-built CSS

function MyForm() {
    return (
        <FormProvider>
            <Input placeholder="Enter your name" />
            <Button>Submit</Button>
        </FormProvider>
    );
}
```

### Option 2: Headless Components (Recommended for production)

```tsx
import {
    UnstyledButton,
    UnstyledInput,
    useFormAnalytics,
} from '@formalia/react/headless';

function MyForm() {
    const analytics = useFormAnalytics();

    return (
        <div>
            <UnstyledInput
                className="border rounded px-3 py-2"
                placeholder="Enter your name"
            />
            <UnstyledButton
                className="bg-blue-500 text-white px-4 py-2 rounded"
                onClick={analytics.trackSubmit}
            >
                Submit
            </UnstyledButton>
        </div>
    );
}
```

### Option 3: CSS Variables Only

```tsx
import '@formalia/react/variables.css';

function MyButton() {
    return (
        <button
            style={{
                backgroundColor: 'hsl(var(--formalia-primary))',
                color: 'hsl(var(--formalia-primary-foreground))',
                borderRadius: 'var(--formalia-radius)',
            }}
        >
            Custom Button
        </button>
    );
}
```

## Customization

### CSS Variables

Override design tokens by setting CSS variables:

```css
:root {
    --formalia-primary: 210 100% 50%;
    --formalia-radius: 0.25rem;
    --formalia-spacing-md: 1.5rem;
}

[data-theme='dark'] {
    --formalia-primary: 210 100% 60%;
    --formalia-background: 222 84% 5%;
}
```

### Available CSS Variables

```css
/* Colors */
--formalia-primary: 221.2 83.2% 53.3%;
--formalia-background: 0 0% 100%;
--formalia-foreground: 222.2 84% 4.9%;
--formalia-border: 214.3 31.8% 91.4%;

/* Spacing */
--formalia-spacing-xs: 0.25rem;
--formalia-spacing-sm: 0.5rem;
--formalia-spacing-md: 1rem;

/* Typography */
--formalia-font-size-sm: 0.875rem;
--formalia-font-size-base: 1rem;

/* Radius */
--formalia-radius: 0.5rem;
```

## API Reference

### Styled Components

-   `Button`, `Input`, `Select`, `Checkbox`, `RadioGroup`
-   `FormProvider`, `Form`, `FormField`
-   `Card`, `Badge`, `Skeleton`, `Toast`

### Headless Components

-   `UnstyledButton`, `UnstyledInput`, `UnstyledSelect`
-   `HeadlessFormFieldRender`, `HeadlessDefaultFormRenderer`

### Hooks & Utilities

-   `useFormAnalytics()` - Form interaction tracking
-   `safeLocalStorage` - Safe localStorage operations
-   `getErrorTranslation()` - Localized error messages

## Framework Support

| Framework | Styled | Headless | CSS Variables |
| --------- | ------ | -------- | ------------- |
| Next.js   | ✅     | ✅       | ✅            |
| Vite      | ✅     | ✅       | ✅            |
| CRA       | ✅     | ✅       | ✅            |
| Remix     | ✅     | ✅       | ✅            |

## Version Compatibility

-   **React**: >=17.0.0
-   **TypeScript**: >=4.5.0
-   **Node.js**: >=16.0.0

## Migration Guide

### From styled to headless

```tsx
// Before (styled)
import { Button } from '@formalia/react';
<Button variant="primary">Submit</Button>;

// After (headless)
import { UnstyledButton } from '@formalia/react/headless';
<UnstyledButton className="btn-primary">Submit</UnstyledButton>;
```

## Best Practices

1. **Use headless for production apps** with existing design systems
2. **Use styled for prototypes** and MVPs
3. **Import CSS variables** if you just need design tokens
4. **Combine approaches** - use headless for custom components, styled for standard ones

## Contributing

See our [contributing guide](./CONTRIBUTING.md) for development setup.

## License

MIT