State directives

SnipForm - Valid States

In some cases, you may want to display a different state if and only if the field is valid.


Basic Usage

Like the Error state, there are three components to a valid state directive:

  1. field: The target field that will trigger the directive if there is no error
  2. option: There are 4 options to valid state directive:
    • show: This will show the element if there is no error
    • text: This will inject the text into the element if there is no error
    • class: This will add a class to the element if there is no error
    • style: This will add a style to the element if there is no error
  3. value: The value of the option if applicable

State parsing order

The state directives are parsed in the following order: valid then error. This means that if you have an element that has triggered both the valid and error states, then the error state will be applied since it overwrote the valid state.


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}-valid-{option}="VALUE"

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

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

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

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

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

It can be read as 'Valid class for email = my-valid-class'

Shorthand format:
The shorthand format is the quickest to write

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

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

This can be read as: 'OK email then class = my-valid-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}-valid-{option}="VALUE"

API (using email as the field):

<div
if-email-valid-show
if-email-valid-text="Literal text to be injected"
if-email-valid-class="my_error_class text-red-500"
if-email-valid-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-valid-show-text="Please use your company email address" />

Examples of each directive (using email as the field)

<!-- Show this element -->
<p if-email-valid-show>There is no error</p>

<!-- Show this element and inject the error text -->
<p if-email-valid-show if-email-valid-text="There is no error"></p>
<!-- OR: -->
<p if-email-valid-show-text="There is no error"></p>

<!-- Show the 'valid-class' if email has no error -->
<input type="email"  name="email"
    sf-validate:email
    if-email-valid-class="valid-class">

<!-- Inject the style "border:2px solid green" if email has no error -->
<input type="email" name="email"
    sf-validate:email
    if-email-valid-style="border:2px solid green"
>

Namespaced format

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

API (using email as the field):

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

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

<div valid-show-text:email="Please use your company email address" />

Examples of each directive (using email as the field)

<!-- Show this element -->
<p valid-show:email>There is no error</p>

<!-- Show this element and inject the text if email has no error -->
<p valid-show:email valid-text:email="There is no error"></p>
<!-- OR: -->
<p valid-show-text:email="There is no error"></p>

<!-- Show the 'valid-class' if email has no error -->
<input type="email"  name="email"
    sf-validate:email
    valid-class:email="valid-class">

<!-- Inject the style "border:2px solid green" if email has no error -->
<input type="email" name="email"
    sf-validate:email
    valid-style:email="border:2px solid green"
>

Shorthand format

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

API (using email as the field):

<div
~email:show
~email:text="Literal text to be injected"
~email:class="my-valid-class text-green-500"
~email:style="border: 1px solid green"
/>

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

<div ~email:show-text="Literal text to be injected" />

Examples of each directive (using email as the field)

<!-- Show this element -->
<p ~email:show>There is no error</p>

<!-- Show this element and inject the error text -->
<p ~email:show ~email:text="There is no error"></p>
<!-- OR: -->
<p ~email:show-text="There is no error"></p>

<!-- Show the 'valid-class' if email has no error -->
<input type="email"  name="email"
        sf-validate:email
        ~email:class="valid-class">

<!-- Inject the style "border:2px solid green" if email has no error -->
<input type="email" name="email"
        sf-validate:email
        ~email:style="border:2px solid green"
>

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-valid-show />

<div valid-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-valid-show
  • valid-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-valid-show

This will be OK:

  • valid-show:first-name
  • ~first-name:show
Previous
Error states