<form-required-checkboxes>

A web component that enables requirement rules for checkbox groups. Enforce exact numbers or ranges of required checkbox selections with built-in validation and multi-language support. See the README for installation and API documentation.

Exact Number Required

Require exactly N checkboxes to be selected.

Require Exactly 3 Selections

This example requires exactly 3 checkboxes to be selected. Try submitting with fewer or more selections to see the validation in action. 

<form-required-checkboxes required="3">
  <fieldset>
    <legend>Choose your top 3 skills</legend>
    <div>
      <label>
        <input type="checkbox" 
               name="skills[]" value="js">
        JavaScript
      </label>
      <label>
        <input type="checkbox" 
               name="skills[]" value="py">
        Python
      </label>
      <label>
        <input type="checkbox" 
               name="skills[]" value="java">
        Java
      </label>
      <label>
        <input type="checkbox" 
               name="skills[]" value="go">
        Go
      </label>
      <label>
        <input type="checkbox" 
               name="skills[]" value="rust">
        Rust
      </label>
    </div>
  </fieldset>
</form-required-checkboxes>
Choose your top 3 skills

Range Required

Require a minimum and maximum number of checkbox selections.

Require 2-4 Selections

This example requires between 2 and 4 checkboxes to be selected. 

<form-required-checkboxes required="2-4">
  <fieldset>
    <legend>Select 2-4 interests</legend>
    <div>
      <label>
        <input type="checkbox" 
               name="interests[]" value="music">
        Music
      </label>
      <label>
        <input type="checkbox" 
               name="interests[]" value="sports">
        Sports
      </label>
      <label>
        <input type="checkbox" 
               name="interests[]" value="reading">
        Reading
      </label>
      <label>
        <input type="checkbox" 
               name="interests[]" value="gaming">
        Gaming
      </label>
      <label>
        <input type="checkbox" 
               name="interests[]" value="cooking">
        Cooking
      </label>
      <label>
        <input type="checkbox" 
               name="interests[]" value="travel">
        Travel
      </label>
    </div>
  </fieldset>
</form-required-checkboxes>
Select 2-4 interests

Maximum Only (Optional)

Set a maximum number of selections with no minimum requirement (0-N).

Up to 3 Selections (Optional)

This example allows up to 3 selections but doesn't require any. The form will fail validation if more than 3 are selected. 

<form-required-checkboxes required="0-3">
  <fieldset>
    <legend>Choose up to 3 toppings</legend>
    <div>
      <label>
        <input type="checkbox" 
               name="toppings[]" value="pepperoni">
        Pepperoni
      </label>
      <label>
        <input type="checkbox" 
               name="toppings[]" value="mushrooms">
        Mushrooms
      </label>
      <label>
        <input type="checkbox" 
               name="toppings[]" value="olives">
        Olives
      </label>
      <label>
        <input type="checkbox" 
               name="toppings[]" value="onions">
        Onions
      </label>
      <label>
        <input type="checkbox" 
               name="toppings[]" value="peppers">
        Peppers
      </label>
    </div>
  </fieldset>
</form-required-checkboxes>
Choose up to 3 toppings

Custom Messages

Override the default notice and error messages with custom text.

Custom Notice and Error Messages

Use the notice and error attributes to provide custom messaging. 

<form-required-checkboxes 
  required="3" 
  notice="Pick exactly 3 colors you like" 
  error="You must select exactly 3 colors">
  <fieldset>
    <legend>Favorite colors</legend>
    <div>
      <label>
        <input type="checkbox" 
               name="colors[]" value="red">
        Red
      </label>
      <label>
        <input type="checkbox" 
               name="colors[]" value="blue">
        Blue
      </label>
      <label>
        <input type="checkbox" 
               name="colors[]" value="green">
        Green
      </label>
      <label>
        <input type="checkbox" 
               name="colors[]" value="yellow">
        Yellow
      </label>
      <label>
        <input type="checkbox" 
               name="colors[]" value="purple">
        Purple
      </label>
    </div>
  </fieldset>
</form-required-checkboxes>
Favorite colors

Localization

The component supports 16 languages out of the box. Use the lang attribute to set the language.

Spanish (Español)

Setting lang="es" displays messages in Spanish. 

<form-required-checkboxes 
  required="2-4" 
  lang="es">
  <fieldset>
    <legend>Opciones</legend>
    <div>
      <label>
        <input type="checkbox" 
               name="opciones[]" value="1">
        Opción 1
      </label>
      <label>
        <input type="checkbox" 
               name="opciones[]" value="2">
        Opción 2
      </label>
      <label>
        <input type="checkbox" 
               name="opciones[]" value="3">
        Opción 3
      </label>
      <label>
        <input type="checkbox" 
               name="opciones[]" value="4">
        Opción 4
      </label>
      <label>
        <input type="checkbox" 
               name="opciones[]" value="5">
        Opción 5
      </label>
    </div>
  </fieldset>
</form-required-checkboxes>
Opciones

French (Français)

Setting lang="fr" displays messages in French. 

<form-required-checkboxes 
  required="3" 
  lang="fr">
  <fieldset>
    <legend>Choix</legend>
    <div>
      <label>
        <input type="checkbox" 
               name="choix[]" value="1">
        Choix 1
      </label>
      <label>
        <input type="checkbox" 
               name="choix[]" value="2">
        Choix 2
      </label>
      <label>
        <input type="checkbox" 
               name="choix[]" value="3">
        Choix 3
      </label>
      <label>
        <input type="checkbox" 
               name="choix[]" value="4">
        Choix 4
      </label>
    </div>
  </fieldset>
</form-required-checkboxes>
Choix

Complete Form Example

The component works seamlessly with other form fields and validation.

Form with Multiple Fields

This demonstrates how the component integrates with standard form fields. The validation runs in the correct order. 

<form>
  <label>
    Email address
    <input type="email" 
           required 
           name="email">
  </label>

  <form-required-checkboxes required="3">
    <fieldset>
      <legend>Choose 3 preferences</legend>
      <div>
        <label>
          <input type="checkbox" 
                 name="prefs[]" value="1">
          Option 1
        </label>
        <label>
          <input type="checkbox" 
                 name="prefs[]" value="2">
          Option 2
        </label>
        <label>
          <input type="checkbox" 
                 name="prefs[]" value="3">
          Option 3
        </label>
        <label>
          <input type="checkbox" 
                 name="prefs[]" value="4">
          Option 4
        </label>
        <label>
          <input type="checkbox" 
                 name="prefs[]" value="5">
          Option 5
        </label>
      </div>
    </fieldset>
  </form-required-checkboxes>

  <button type="submit">Submit</button>
</form>
Choose 3 preferences

API Reference

For complete documentation, see the README: