Currently, we can only make checkboxes required or not, individually. In some cases you need to be able to set a specific number of checkboxes that need to be checked. The form-required-checkboxes web component enables that.
This component ships with full TypeScript definitions (.d.ts), enabling type-safe usage in TypeScript projects and improved autocompletion in editors. Types are exported in the package and automatically picked up by modern build tools.
All key properties (required, notice, error, lang) are now fully reflected as attributes, ensuring compatibility with frameworks and declarative usage. The component also implements an internal _upgradeProperty method for seamless property/attribute sync when used with frameworks that set properties before element definition.
npm install @aarongustafson/form-required-checkboxes
Import the class and define the custom element with your preferred tag name:
import { FormRequiredCheckboxesElement } from '@aarongustafson/form-required-checkboxes';
// Define with default name
customElements.define(
'form-required-checkboxes',
FormRequiredCheckboxesElement,
);
// Or define with a custom name
customElements.define('my-checkbox-group', FormRequiredCheckboxesElement);
Use the guarded definition helper to register the element when customElements is available:
import '@aarongustafson/form-required-checkboxes/define.js';
If you prefer to control when the element is registered, call the helper directly:
import { defineFormRequiredCheckboxes } from '@aarongustafson/form-required-checkboxes/define.js';
defineFormRequiredCheckboxes();
You can also include the guarded script from HTML:
<script
src="./node_modules/@aarongustafson/form-required-checkboxes/define.js"
type="module"
></script>
You can also use the component directly from a CDN:
<script
src="https://unpkg.com/@aarongustafson/form-required-checkboxes@latest/define.js"
type="module"
></script>
required - Represents the range of required values.
notice (optional) - The description that explains details of the required value in plain language. If you don't supply one, the component will create one for you based on the current language. This description will be added as a small element within the component (as a sibling to the fieldset)error (optional) - The validation error you'd like to show when the validation criteria is not met. If not provided, an appropriate error message will be generated based on the current language.lang (optional) - Language code for localized messages (e.g., "en", "es", "fr", "de"). Falls back to the nearest ancestor's lang attribute or the document language.FormRequiredCheckboxesElement.registerTranslations(translations) - Register custom translations or override existing ones. See the Localization section below for details.The component includes built-in translations for 16 languages. Messages are automatically generated based on the lang attribute.
Supported languages:
Regional language codes (e.g., en-US, es-MX) automatically fall back to their base language.
<form-required-checkboxes required="3" lang="es">
<fieldset>
<legend>Opciones</legend>
<!-- Will display: "Elija 3 de la lista" -->
</fieldset>
</form-required-checkboxes>
The component will automatically detect the language from:
lang attribute on the element itselflang attribute on the nearest ancestor elementlang attributeYou can register custom translations or override existing ones:
import { FormRequiredCheckboxesElement } from '@aarongustafson/form-required-checkboxes/form-required-checkboxes.js';
FormRequiredCheckboxesElement.registerTranslations({
pt: {
exact: 'Escolha {n} da lista',
max: 'Escolha até {n} da lista',
range: 'Escolha entre {min} e {max} da lista',
error_exact: 'Você deve escolher exatamente {n} opções',
error_range: 'Você deve escolher entre {min} e {max} opções',
},
});
You can override just specific messages for a language:
FormRequiredCheckboxesElement.registerTranslations({
en: {
exact: 'Pick exactly {n} items',
// Other messages will use defaults
},
});
You can still override messages on individual instances using attributes:
<form-required-checkboxes
required="3"
notice="Select exactly 3 items please"
error="You must select 3 items"
>
<!-- ... -->
</form-required-checkboxes>
This web component assumes you will be marking up your checkbox group in a fieldset with a legend and that all of the checkboxes share a name (e.g., "foo[]").
<form>
<form-required-checkboxes required="3">
<fieldset>
<legend>Choose your top 3 preferences</legend>
<label
><input type="checkbox" name="preferences[]" value="1" /> Option
1</label
>
<label
><input type="checkbox" name="preferences[]" value="2" /> Option
2</label
>
<label
><input type="checkbox" name="preferences[]" value="3" /> Option
3</label
>
<label
><input type="checkbox" name="preferences[]" value="4" /> Option
4</label
>
<label
><input type="checkbox" name="preferences[]" value="5" /> Option
5</label
>
</fieldset>
</form-required-checkboxes>
<button type="submit">Submit</button>
</form>
<form-required-checkboxes required="2-4">
<fieldset>
<legend>Choose 2-4 items</legend>
<label><input type="checkbox" name="items[]" value="a" /> Item A</label>
<label><input type="checkbox" name="items[]" value="b" /> Item B</label>
<label><input type="checkbox" name="items[]" value="c" /> Item C</label>
<label><input type="checkbox" name="items[]" value="d" /> Item D</label>
<label><input type="checkbox" name="items[]" value="e" /> Item E</label>
</fieldset>
</form-required-checkboxes>
<form-required-checkboxes required="0-3">
<fieldset>
<legend>Choose up to 3 options (optional)</legend>
<label
><input type="checkbox" name="options[]" value="x" /> Option
X</label
>
<label
><input type="checkbox" name="options[]" value="y" /> Option
Y</label
>
<label
><input type="checkbox" name="options[]" value="z" /> Option
Z</label
>
</fieldset>
</form-required-checkboxes>
<form-required-checkboxes
required="3"
notice="You must select exactly 3 skills"
error="Please select exactly 3 skills to continue"
>
<fieldset>
<legend>Select your top 3 skills</legend>
<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
>
</fieldset>
</form-required-checkboxes>
This web component works in all modern browsers that support:
For older browsers, you may need polyfills for Custom Elements.
The component adds no stylesheet. Keep the native checkboxes, labels, fieldset,
and legend, and give the generated small notice a foreground that’s readable
on its actual background. Don’t use color alone to explain selection limits or
errors. Supply notice and error text for an instance, or use the localization
API for translated messages.
The demos pair page text with Canvas, button and inline-code text with
ButtonFace, and text fields and code blocks with Field. Supporting text
inside a group inherits its foreground; the Canvas-backed footer uses an 80%
foreground mix, with full-strength text in forced colors and increased contrast.
Button hover adds a small foreground wash and an underline without fading the
label. Forced colors use solid Field and ButtonFace backgrounds for their
paired text, so readability doesn’t depend on gradients that browsers may suppress.
Native checkbox painting and keyboard focus remain browser-controlled.
Keep foreground/background pairs together when overriding these styles, and
test text, boundaries, and focus on every adjacent surface.
Before upgrade, or if the module fails, the authored checkboxes, labels, and
selection limits remain available. Count validation needs JavaScript; native
HTML required cannot enforce a group’s exact count or range. Always validate
selections on the server too. In the enhanced demo, invalid submission uses the
browser’s validation message and focuses the first checkbox when appropriate;
valid submission shows authored status text without sending data. Changing a
checkbox clears the component’s custom validity. Native reset restores checkbox
values, but does not itself clear an existing custom error; change a checkbox
before resubmitting after an invalid attempt.
Browser tests cover the three import pages in bundled Chromium, Firefox, and
WebKit, including 19 recorded study palettes, keyboard use, native validation,
localized notices, 320px reflow with enlarged text, and module-failure and
no-JavaScript fallbacks. Palette substitution is a regression aid, not a test of
OS repainting or browser validation-tooltip contrast. Actual Windows Contrast
themes, Firefox forced-color preferences, shipping mobile browsers, platform
accent changes, and assistive-technology checks remain manual work. Ubuntu
WebKit’s known dark ButtonText/ButtonFace contrast limitation is an isolated
expected failure, not a passing contrast result.
# Run tests
npm test
# Run tests once
npm run test:run
# Run tests with UI
npm run test:ui
# Run tests with coverage
npm run test:coverage
# Install browser engines once, then run with one worker
npx playwright install chromium firefox webkit
npm run test:browser
# Local no-cache demo preview
PORT=3013 node scripts/serve.js
# Check JavaScript, declarations, HTML, CSS, Markdown, JSON, and workflows
npm run lint
# Format code
npm run format
.d.ts file and package export for full TypeScript support.required, notice, error, lang) now reflect as attributes for framework compatibility.requestAnimationFrame for initialization, optimizes DOM queries, and ensures all event listeners are cleaned up in disconnectedCallback.