SnipForm - Error States

The SnipForm engine has error states built in to help you guide your users to the right information. You can use these error states to help your users understand what they need to do to fix the error.

The errors are return if there are validation rules that were not met. You can read more about validation rules in the documentation.

Basic Usage

There are three components to an error state directive:

field: The target field that will trigger the directive should it have an error
option: There are 4 options to error state directive:
- show: This will show the element if there is an error
- text: This will inject the text of the error into the element
- class: This will add a class to the element if there is an error
- style: This will add a style to the element if there is an error
value: The value of the option if applicable

Based on your personal preference or requirements, there are three formats you can use:

Readability format:
The readability format is, as the name suggests, the easiest to read and remember. It is also the most verbose.

It's in the form of a statement: `if-{field}-error-{option}="VALUE"

<input if-email-error-class="my-error-class" />

It can be read as 'If email error then class = my-error-class'

Namespaced format:
The Namespaced format is quick to write and easy to understand.

The format is: error-{option}:{field}="VALUE".

<input error-class:email="my-error-class" />

It can be read as 'Error class for email = my-error-class'

Shorthand format:
The shorthand format is the quickest to write

The format is: !{field}:{option}="VALUE".

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

The bang (!) operator is synonymous with NOT in development, thus it can be read as: 'NOT email then class = my-error-class'

Shorthand is best for static sites

In some cases, the Shorthand format may interfere with existing JS dependencies. In most cases though, especially for static sites, the Shorthand format will work well and is usually the preferred option.

Note on style option

Using !important in the style value will not work.

Readability format

Format: if-{field}-error-{option}="VALUE"

API (using email as the field):

<div
if-email-error-show
if-email-error-text
if-email-error-text="Literal text to be injected"
if-email-error-class="my-error-class text-red-500"
if-email-error-style="border: 1px solid red"
/>

Since show and text often go together, for convenience you can combine them in a single directive:

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

Examples of each directive (using email as the field)

<!-- Show this element -->
<p if-email-error-show>There was an error</p>

<!-- Show this element and inject the error text -->
<p if-email-error-show if-email-error-text></p>
<!-- OR: -->
<p if-email-error-show-text></p>

<!-- Show this element and inject the error text literal -->
<p if-email-error-show if-email-error-text="This text will show no matter what the error says"></p>
<!-- OR: -->
<p if-email-error-show-text="This text will show no matter what the error says"></p>
<!-- OR simply -->
<p if-email-error-show">This text will show no matter what the error says</p>

<!-- Show the 'error-class' if email did not validate -->
<input type="email"  name="email"
    sf-validate:email
    if-email-error-class="error-class">

<!-- Inject the style "border:2px solid red" if email did not validate -->
<input type="email" name="email"
    sf-validate:email
    if-email-error-style="border:2px solid red"
>

Namespaced format

Format: error-{option}:{field}="VALUE"

API (using email as the field):

`<div
error-show:email
error-text:email
error-text:email="Literal text to be injected"
error-class:email="my_error_class text-red-500"
error-style:email="border: 1px solid red"
/>`

Since show and text often go together, for convenience you can combine them in a single directive:

<div error-show-text:email />

Examples of each directive (using email as the field)

<!-- Show this element -->
<p error-show:email>There was an error</p>

<!-- Show this element and inject the error text -->
<p error-show:email error-text:email></p>
<!-- OR: -->
<p error-show-text:email></p>

<!-- Show this element and inject the error text literal -->
<p error-show:email error-text:email="This text will show no matter what the error says"></p>
<!-- OR: -->
<p error-show-text:email="This text will show no matter what the error says"></p>
<!-- OR simply -->
<p error-show:email>This text will show no matter what the error says</p>

<!-- Show the 'error-class' if email did not validate -->
<input type="email"  name="email"
    sf-validate:email
    error-class:email="error-class">

<!-- Inject the style "border:2px solid red" if email did not validate -->
<input type="email" name="email"
    sf-validate:email
    error-style:email="border:2px solid red"
>

Shorthand format

Format: !{field}:{option}="VALUE"

API (using email as the field):

<div
!email:show
!email:text
!email:text="Literal text to be injected"
!email:class="my_error_class text-red-500"
!email:style="border: 1px solid red"
/>

Since show and text often go together, for convenience you can combine them in a single directive:

<div !email:show-text />

Examples of each directive (using email as the field)


<!-- Show this element -->
<p !email:show>There was an error</p>

<!-- Show this element and inject the error text -->
<p !email:show !email:text></p>
<!-- OR: -->
<p !email:show-text></p>

<!-- Show this element and inject the error text literal -->
<p !email:show !email:text="This text will show no matter what the error says"></p>
<!-- OR: -->
<p !email:show-text="This text will show no matter what the error says"></p>
<!-- OR simply -->
<p !email:show>This text will show no matter what the error says</p>

<!-- Show the 'error-class' if email did not validate -->
<input type="email"  name="email"
    sf-validate:email
    !email:class="error-class"
>

<!-- Inject the style "border:2px solid red" if email did not validate -->
<input type="email" name="email"
    sf-validate:email
    !email:style="border:2px solid red"
>

If any error

In same cases you may want to show an error if any of the fields are invalid. You can do this in any of the desired formats by using:

<!-- Readability format, omit the field -->
<section if-error-show>
    There were errors, OMG!
</section>

<!-- Namespace format, omit the field -->
<section error-show:>
   There were errors, OMG!
</section>

<!-- Shorthand format, use `[any]` as field -->
<section ![any]:show>
    There were errors, OMG!
</section>

API:

<!--Readability -->
<div
if-error-show
if-error-text="Literal text to be injected"
if-error-class="my_error_class text-red-500"
if-error-style="border: 1px solid red"
/>

<!- Namespaced -->
<div
error-show:
error-text:="Literal text to be injected"
error-class:="my_error_class text-red-500"
error-style:="border: 1px solid red"
/>

<!- Shorthand -->
<div
![any]:show
![any]:text="Literal text to be injected"
![any]:class="my_error_class text-red-500"
![any]:style="border: 1px solid red"

/>

Text option must have a value

Since the any error directive can be invoked for any number of error fields, the text value cannot come from the error itself, so it must be a literal value.

However, this is seldom used since the element can be pre-populated with the desired text/content and invoked with the show option rather. But it is available if you need it.

Note on field names

If your field name has more than one word, then it is recommended to use underscores. For example, first_name will be used as:

<div if-first_name-error-show />

<div error-show:first_name />

<div !first_name:show />

Field names should be underscored

As stated in the Field name limitations section, field names should be underscored. This is because the SnipForm engine directive parser will look for the field name in the directive and will not be able to find it if it has spaces.

This will NOT work:

if-first name-error-show
error-show:first name
!first name:show

Hyphenated field names are ok, but with limitations. You will be able to use a hyphenated field name in the Namespaced and Shorthand formats, but not in the Readability format.

This will NOT work:

if-first-name-error-show

This will be OK:

error-show:first-name
!first-name:show