# SnipForm DDF - Complete Reference

> Directive Driven Forms - The form backend that actually handles everything.

## Why SnipForm

### The Problem with Traditional Form Backends

Every form backend works the same way: POST your data to their endpoint, they store it, send you an email. That's it. You still have to:

- Write JavaScript for validation
- Build your own error display logic
- Handle loading states manually
- Create success/thank you screens
- Figure out spam protection yourself

You're doing all the work. They're just receiving a POST request.

### What Makes SnipForm Different

SnipForm flips the model. Instead of "here's an endpoint, good luck", you get a complete form engine that runs on your page:

**Directive-Driven**: Validation, error states, loading states, success content - all declared in HTML attributes. No JavaScript to write.

```html
<input name="email"
       sf-validate:required
       sf-validate:email="Invalid email"
       error-class="border-red-500"
       valid-class="border-green-500" />
<span if-error="email" then-show-text></span>
```

That's a validated input with error display, error/valid styling - zero JavaScript.

**Fully State-Managed AJAX Form**: The ~8KB library (gzipped) handles:
- Form state (pristine, touched, submitting, success, error)
- Field validation with 30+ rules (server-verified, can't be bypassed)
- Reactive error/valid state on inputs and display elements
- Loading/submit state UI (spinners, button text, overlays)
- Success content with field interpolation
- SPA navigation support with proper cleanup

**Behavioral Spam Scoring**: Not just honeypots. The library tracks:
- Time from page interaction to submit
- Keystroke patterns
- Focus events and field touches
- Mouse movement and scrolling
- WebDriver detection
- Datacenter IP detection

Submissions get scored. Bots get fake success responses (they think it worked, nothing saved). Real users aren't affected by CAPTCHAs.

**No Submit Limits**: Free plan has no submission limits. Not "100/month free" or "first 50 free". Unlimited.

**No Cookies**: SnipForm doesn't use cookies. No cookie consent banners needed. GDPR-friendly out of the box.

### When to Use SnipForm

- Static sites (Astro, Next.js static, Hugo, Jekyll, plain HTML)
- Jamstack / serverless architectures
- Any site where you don't want to build a form backend
- When you want validation that can't be bypassed (server-side)
- When you hate writing form JavaScript

---

## Quick Start

```html
<!-- 1. Wrap your form with snip-form -->
<snip-form key="YOUR_FORM_KEY">
    <form>
        <!-- 2. Add validation directives to inputs -->
        <input name="email" sf-validate:required sf-validate:email="Invalid email" />

        <!-- 3. Add error display -->
        <span if-error="email" then-show-text></span>

        <button type="submit">Submit</button>
    </form>

    <!-- 4. Optional: Custom success content -->
    <sf-success>
        <h2>Thank you %email%!</h2>
    </sf-success>
</snip-form>

<!-- 5. Include the script (8KB gzipped) -->
<script src="https://cdn.snipform.io/api/v2/sf.iife.js"></script>
```

Get your form key at https://app.snipform.io (free, no submit limits).

---

## Container Element

### `<snip-form>`

Wraps your form. Required attributes:

| Attribute | Description |
|-----------|-------------|
| `key="FORM_KEY"` | Your form's unique key (from dashboard) |
| `transition="ms"` | Fade transition duration in milliseconds (default: 150) |
| `transition="none"` | Disable transitions |
| `mode="test"` | Test mode - form won't actually submit |

```html
<snip-form key="abc123" transition="500">
    <form>...</form>
</snip-form>
```

---

## Validation Directives

Add to `<input>`, `<select>`, or `<textarea>` elements. Validation happens server-side and cannot be bypassed by disabling JavaScript.

### Syntax

```html
<!-- Basic: uses default error message -->
<input sf-validate:rule />

<!-- With custom error message -->
<input sf-validate:rule="Your custom error message" />

<!-- With parameter -->
<input sf-validate:rule[param]="Error message" />

<!-- Multiple rules (all must pass) -->
<input sf-validate:required sf-validate:email sf-validate:max_length[255] />
```

### Basic Validation

| Directive | Description |
|-----------|-------------|
| `sf-validate:required` | Field must have a value |
| `sf-validate:email` | Valid email format |
| `sf-validate:url` | Valid URL format |
| `sf-validate:active_url` | URL with existing/resolvable domain |

### Text Validation

| Directive | Description |
|-----------|-------------|
| `sf-validate:alpha` | Letters only (a-z, A-Z) |
| `sf-validate:alpha_num` | Letters and numbers only |
| `sf-validate:alpha_dash` | Letters, numbers, dashes, underscores |
| `sf-validate:min_length[n]` | Minimum character length |
| `sf-validate:max_length[n]` | Maximum character length |
| `sf-validate:starts_with[str]` | Must start with string |
| `sf-validate:ends_with[str]` | Must end with string |

### Numeric Validation

| Directive | Description |
|-----------|-------------|
| `sf-validate:numeric` | Must be a number |
| `sf-validate:integer` | Must be an integer |
| `sf-validate:min[n]` | Minimum value (for numbers) or length (for strings) |
| `sf-validate:max[n]` | Maximum value or length |
| `sf-validate:between[min,max]` | Value must be between min and max |

### Date Validation

| Directive | Description |
|-----------|-------------|
| `sf-validate:date` | Valid date format |
| `sf-validate:after[date]` | Date must be after reference |
| `sf-validate:before[date]` | Date must be before reference |
| `sf-validate:after_or_equal[date]` | Date on or after reference |
| `sf-validate:before_or_equal[date]` | Date on or before reference |

Date references can be: `today`, `tomorrow`, `yesterday`, a date string (`2025-12-31`), or another field name.

### Comparison Validation

| Directive | Description |
|-----------|-------------|
| `sf-validate:same[field]` | Must match another field's value |
| `sf-validate:different[field]` | Must differ from another field |
| `sf-validate:in[a,b,c]` | Must be one of the listed values |
| `sf-validate:not_in[x,y,z]` | Must not be any of the listed values |

### Boolean Validation

| Directive | Description |
|-----------|-------------|
| `sf-validate:boolean` | Must be true/false, 1/0, yes/no |
| `sf-validate:accepted` | Must be checked/true/yes/1 (for checkboxes) |

---

## Error State Directives

Control what happens when a field has a validation error.

### On Error Display Elements

Add to any element (usually `<span>`, `<div>`, `<p>`):

| Directive | Description |
|-----------|-------------|
| `if-error="field_name"` | Target this element for the specified field's error state |
| `then-show` | Show element when field has error |
| `then-hide` | Hide element when field has error |
| `then-show-text` | Show element AND display the error message |
| `then-text="msg"` | Set custom text when error (or use `true` for API message) |
| `then-class="classes"` | Add classes when error |
| `then-style="styles"` | Add inline styles when error |

### On Valid Display (else-* directives)

| Directive | Description |
|-----------|-------------|
| `else-hide` | Hide element when field is valid |
| `else-text="msg"` | Set text when field is valid |
| `else-class="classes"` | Add classes when valid |
| `else-style="styles"` | Add inline styles when valid |

### On Input Elements

Add directly to `<input>`, `<select>`, `<textarea>`:

| Directive | Description |
|-----------|-------------|
| `error-class="classes"` | Add classes when this input has error |
| `error-style="styles"` | Add inline styles when error |
| `valid-class="classes"` | Add classes when this input is valid |
| `valid-style="styles"` | Add inline styles when valid |

### Examples

```html
<!-- Show error message text -->
<input name="email" sf-validate:email />
<span if-error="email" then-show-text></span>

<!-- Toggle between error and valid messages -->
<input name="email" sf-validate:email />
<span if-error="email"
      then-show-text then-class="text-red-500"
      else-text="Looks good!" else-class="text-green-500"></span>

<!-- Hide helper text when valid -->
<input name="phone" sf-validate:starts_with[+]="Use international format" />
<span if-error="phone" then-show-text else-hide>Format: +1 555 123 4567</span>

<!-- Input styling on error/valid -->
<input name="email" sf-validate:email
       error-class="border-red-500 ring-red-500"
       valid-class="border-green-500 ring-green-500" />
```

---

## Submit/Loading State Directives

Control element appearance during form submission.

### On Any Element

| Directive | Description |
|-----------|-------------|
| `on-submit-show` | Show element during submit (hidden by default) |
| `on-submit-hide` | Hide element during submit |
| `on-submit-class="classes"` | Add classes during submit |
| `on-submit-text="text"` | Change text during submit |
| `on-submit-style="styles"` | Add inline styles during submit |

### Examples

```html
<!-- Loading overlay (hidden until submit) -->
<div on-submit-show class="loading-overlay" style="display:none">
    <div class="spinner"></div>
</div>

<!-- Button state change -->
<button type="submit"
        on-submit-text="Sending..."
        on-submit-class="opacity-50 cursor-wait"
        on-submit-style="pointer-events: none">
    Submit
</button>

<!-- Hide form content during submit -->
<div on-submit-hide class="form-fields">
    <input name="email" />
</div>
```

---

## Success Content

### `<sf-success>`

Custom content shown after successful submission. Place inside `<snip-form>`, outside `<form>`.

### Field Interpolation

Use `%field_name%` to insert submitted values:

```html
<sf-success style="display:none">
    <div class="success-message">
        <h2>Thank you, %name%!</h2>
        <p>We'll contact you at %email%.</p>
    </div>
</sf-success>
```

---

## Complete Example

```html
<snip-form key="YOUR_KEY" transition="750">
    <form>
        <!-- Loading overlay (hidden by default) -->
        <div on-submit-show class="loader-overlay" style="display:none">
            <div class="spinner"></div>
        </div>

        <div class="field">
            <label>Full Name</label>
            <input name="full_name" sf-validate:required="Please enter your name"
                error-class="input-error" valid-class="input-valid" />
            <span if-error="full_name" then-show-text else-hide></span>
        </div>

        <div class="field">
            <label>Email</label>
            <input name="email" sf-validate:email
                error-class="input-error" valid-class="input-valid" />
            <span if-error="email" then-show-text then-class="error-text"
                else-text="Valid email!" else-class="valid-text"></span>
        </div>

        <div class="field">
            <label>Mobile</label>
            <input name="mobile" sf-validate:starts_with[+]="Use international format"
                error-class="input-error" />
            <span if-error="mobile" then-show-text class="helper-text">
                International format starting with +
            </span>
        </div>

        <div class="field">
            <label>Message</label>
            <textarea name="message" sf-validate:required
                sf-validate:min_length[10]="Message too short (min 10 chars)"
                error-class="input-error"></textarea>
            <span if-error="message" then-show-text else-hide></span>
        </div>

        <div class="field">
            <input name="terms" type="checkbox" value="yes"
                sf-validate:accepted="Please accept the terms" />
            <label>I accept the terms</label>
            <span if-error="terms" then-show-text else-hide></span>
        </div>

        <button type="submit"
            on-submit-class="btn-loading"
            on-submit-text="Submitting..."
            on-submit-style="opacity: 0.7">Submit</button>
    </form>

    <sf-success style="display:none">
        <div class="success-content">
            <h2>Thank you %full_name%!</h2>
            <p>We'll respond to %email% shortly.</p>
        </div>
    </sf-success>
</snip-form>
```

---

## All Validation Rules Reference

### Required & Format
- `required` - Field cannot be empty
- `email` - Valid email format
- `url` - Valid URL format
- `active_url` - URL that resolves to real domain

### Text Patterns
- `alpha` - Letters only
- `alpha_num` - Letters and numbers
- `alpha_dash` - Letters, numbers, dashes, underscores
- `starts_with[prefix]` - Must start with prefix
- `ends_with[suffix]` - Must end with suffix

### Length & Size
- `min[n]` - Minimum value/length
- `max[n]` - Maximum value/length
- `min_length[n]` - Minimum characters
- `max_length[n]` - Maximum characters
- `between[min,max]` - Between range

### Numbers
- `numeric` - Must be numeric
- `integer` - Must be integer

### Dates
- `date` - Valid date
- `after[ref]` - After date/field
- `before[ref]` - Before date/field
- `after_or_equal[ref]` - On or after
- `before_or_equal[ref]` - On or before

### Comparison
- `same[field]` - Matches field
- `different[field]` - Different from field
- `in[a,b,c]` - One of values
- `not_in[a,b,c]` - None of values

### Boolean
- `boolean` - true/false, 1/0, yes/no
- `accepted` - Checked or truthy

---

## Directive Quick Reference

### Validation (on inputs)
```
sf-validate:rule="Error message"
sf-validate:rule[param]="Error message"
```

### Error States (on display elements)
```
if-error="field"      - Target field
then-show             - Show on error
then-hide             - Hide on error
then-show-text        - Show + display error message
then-text="msg"       - Custom error text
then-class="cls"      - Error classes
then-style="css"      - Error styles
```

### Valid States (on display elements)
```
else-hide             - Hide when valid
else-text="msg"       - Valid text
else-class="cls"      - Valid classes
else-style="css"      - Valid styles
```

### Input Styling (on inputs)
```
error-class="cls"     - Classes on error
error-style="css"     - Styles on error
valid-class="cls"     - Classes on valid
valid-style="css"     - Styles on valid
```

### Submit States (on any element)
```
on-submit-show        - Show during submit
on-submit-hide        - Hide during submit
on-submit-text="msg"  - Text during submit
on-submit-class="cls" - Classes during submit
on-submit-style="css" - Styles during submit
```

### Container
```
<snip-form key="KEY" transition="ms">
```

### Success Content
```
<sf-success>%field% interpolation</sf-success>
```

---

## Common Patterns

### Password Confirmation
```html
<input name="password" type="password" sf-validate:required sf-validate:min_length[8] />
<input name="password_confirm" type="password" sf-validate:same[password]="Passwords must match" />
```

### Terms Checkbox
```html
<input name="terms" type="checkbox" value="yes" sf-validate:accepted="Please accept the terms" />
```

### International Phone
```html
<input name="phone" sf-validate:starts_with[+]="Use international format (+1, +44, etc.)" />
```

### Age Verification
```html
<input name="age" type="number" sf-validate:min[18]="Must be 18 or older" />
```

### Future Date
```html
<input name="start_date" type="date" sf-validate:after[today]="Must be a future date" />
```

### Toggle Error/Valid Message
```html
<span if-error="email"
      then-show-text then-class="text-red-500"
      else-text="Valid!" else-class="text-green-500"
      style="display:none"></span>
```

### Helper Text That Hides on Valid
```html
<span if-error="field" then-show-text else-hide>
    Default helper text shown initially
</span>
```

---

## Technical Details

- **Library size**: ~21KB raw, ~8KB gzipped
- **Dependencies**: None (vanilla JS with embedded Preact Signals)
- **Browser support**: All modern browsers
- **SPA support**: Works with Astro, Next.js, React Router, Vue Router (proper cleanup on navigation)
- **Validation**: Server-side (cannot be bypassed by disabling JS)
- **Spam protection**: Behavioral scoring, honeypots, IP verification, WebDriver detection
- **Cookies**: None - no cookie consent banners needed
- **Submit limits**: None, even on free plan

---

*Get your form key at https://app.snipform.io (free, no submit limits)*
*Documentation: https://docs.snipform.io*
*Examples: https://snipform.io/examples/*