Upgrade Guide

This guide covers migrating from SnipForm Forms V1 to V2. The V2 API is simpler with a single directive format, improved performance, and better IDE support.

Quick Changes

Change	V1	V2
Script URL	/wrap/sf.iife.js	/api/v2/sf.iife.js
Success element	<sf-result>	<sf-success>
Directive formats	3 formats	1 format

---

1. Update Script URL

V1:

<script src="https://cdn.snipform.io/wrap/sf.iife.js" defer></script>

V2:

<script src="https://cdn.snipform.io/api/v2/sf.iife.js" defer></script>

---

2. Update Success Element

Rename <sf-result> to <sf-success>:

V1:

<sf-result style="display:none">
    <h2>Thanks %name%!</h2>
</sf-result>

V2:

<sf-success style="display:none">
    <h2>Thanks %name%!</h2>
</sf-success>

Note

Variable substitution (%fieldname%) works the same in V2.

---

3. Update Error State Directives

V1 had three directive formats. V2 uses a single, cleaner format.

Show Error Messages

V1 (Readability):

<p if-email-error-show if-email-error-text></p>

V1 (Namespace):

<p error-show:email error-text:email></p>

V1 (Shorthand):

<p !email:show !email:text></p>

V2:

<p if-error="email" then-show then-text style="display:none"></p>

Error Classes on Inputs

V1:

<input if-email-error-class="error-class" />
<input error-class:email="error-class" />
<input !email:class="error-class" />

V2:

<input error-class="error-class" />

Note

In V2, error-class on an input automatically applies to that field - no field name needed.

Error Styles

V1:

<input if-email-error-style="border: 2px solid red" />
<input error-style:email="border: 2px solid red" />
<input !email:style="border: 2px solid red" />

V2:

<input error-style="border: 2px solid red" />

---

4. Update Valid State Directives

Valid Classes

V1:

<input if-email-valid-class="valid-class" />
<input valid-class:email="valid-class" />
<input ~email:class="valid-class" />

V2:

<input valid-class="valid-class" />

Valid Text

V1:

<p if-email-valid-show if-email-valid-text="Email is valid"></p>

V2:

<div if-error="email">
    <p else-text>Email is valid</p>
</div>

---

5. Update Submit State Directives

V1:

<div submit:show>Submitting...</div>
<button submit:text="Saving...">Save</button>
<input submit:class="disabled">

V2:

<div on-submit-show style="display:none">Submitting...</div>
<button on-submit-text="Saving...">Save</button>
<input on-submit-class="disabled">

---

6. Disable Parser Attributes (Removed)

V1 had attributes to disable specific parsers:

<!-- V1 - No longer needed in V2 -->
<snip-form readability="false">
<snip-form namespace="false">
<snip-form shorthand="false">

V2 has only one format, so these are no longer needed.

---

Complete Migration Example

V1 Form

<snip-form key="YOUR_KEY">
    <form>
        <input name="email"
            sf-validate:required
            sf-validate:email
            if-email-error-class="border-red-500"
            if-email-valid-class="border-green-500" />

        <p if-email-error-show-text style="display:none"></p>

        <button type="submit" submit:text="Sending...">
            Send
        </button>
    </form>

    <sf-result style="display:none">
        <p>Thanks %email%!</p>
    </sf-result>
</snip-form>

<script src="https://cdn.snipform.io/wrap/sf.iife.js" defer></script>

V2 Form

<snip-form key="YOUR_KEY">
    <form>
        <input name="email"
            sf-validate:required
            sf-validate:email
            error-class="border-red-500"
            valid-class="border-green-500" />

        <p if-error="email" then-show then-text style="display:none"></p>

        <button type="submit" on-submit-text="Sending...">
            Send
        </button>
    </form>

    <sf-success style="display:none">
        <p>Thanks %email%!</p>
    </sf-success>
</snip-form>

<script src="https://cdn.snipform.io/api/v2/sf.iife.js" defer></script>

---

Conversion Reference Table

V1 Attribute	V2 Attribute
if-{field}-error-show	if-error="{field}" then-show
if-{field}-error-text	if-error="{field}" then-text
if-{field}-error-class	error-class (on input) or if-error then-class
if-{field}-error-style	error-style (on input) or if-error then-style
error-show:{field}	if-error="{field}" then-show
error-text:{field}	if-error="{field}" then-text
error-class:{field}	error-class (on input)
!{field}:show	if-error="{field}" then-show
!{field}:text	if-error="{field}" then-text
!{field}:class	error-class (on input)
if-{field}-valid-class	valid-class (on input)
valid-class:{field}	valid-class (on input)
~{field}:class	valid-class (on input)
submit:show	on-submit-show
submit:text	on-submit-text
submit:class	on-submit-class
loading:show	Removed in V2
loading:class	Removed in V2
<sf-result>	<sf-success>

---

IDE Support

V2 includes IDE autocomplete support. Install the intellisense package:

npm

npm install -D @snipform/html-intellisense

yarn

yarn add -D @snipform/html-intellisense

pnpm

pnpm add -D @snipform/html-intellisense

Works with VS Code, WebStorm, PhpStorm, and other JetBrains IDEs. See IDE Setup for configuration.