Checkbox
pivot-checkbox is a checkbox group web component that renders a labelled <fieldset> containing one or more <input type="checkbox"> / <label> pairs. Options are driven entirely by the pivot-options property. The component uses native HTML form controls throughout, so browser constraint validation, accessibility semantics, and keyboard behavior are all handled by the platform.
Quick Start
<!-- Basic checkbox group -->
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>
<!-- Pre-selected options (multiple) -->
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-value='["design", "research"]'
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>
<!-- Pre-selected option (single — plain string is also accepted) -->
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-value="design"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>
<!-- Required with helper text -->
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-required
pivot-helper-text="Select at least one option to continue"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" }
]'
></pivot-checkbox>
<!-- Error state -->
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-error
pivot-error-text="Please select at least one option"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" }
]'
></pivot-checkbox>
<!-- Disabled group -->
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-disabled
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" }
]'
></pivot-checkbox>Implementation Notes
-
pivot-nameis required for correct grouping behavior. All generated<input type="checkbox">elements share this name. Without it, the browser cannot associate them as a group and form submissions will not key the values correctly. -
pivot-optionsdrives all rendered options. It can be set as a JSON string attribute (as shown above) or as a JavaScript property:const checkbox = document.querySelector("pivot-checkbox");
checkbox.pivotOptions = [
{ label: "Design", value: "design" },
{ label: "Engineering", value: "engineering" },
{ label: "Research", value: "research" },
]; -
pivot-valuepre-selects one or more options by matching each entry against optionvaluefields. Pass a JSON array string to pre-check multiple items, or a plain string to pre-check a single item:<!-- Multiple pre-selected -->
<pivot-checkbox pivot-value='["design", "research"]' ...></pivot-checkbox>
<!-- Single pre-selected (plain string accepted for convenience) -->
<pivot-checkbox pivot-value="design" ...></pivot-checkbox>As a JavaScript property, assign an array directly:
checkbox.pivotValue = ["design", "research"]; -
Helper and error text rendering is delegated to
pivot-field-helper-message. The message region is only rendered when there is helper text,pivot-error-text, or a native validation message to show; otherwise the region is omitted entirely. See thepivot-field-helper-messagedocumentation for details on its rendering logic. -
Error text replaces
pivot-helper-textwhile it is shown. Settingpivot-error-texton its own is enough to show the error icon, message, and error styling. Settingpivot-erroralone applies error styling to the options without a message, and helper text stays visible. See Validation and Error Display for how native validation messages fit in. -
In Angular, use dot-prefix property binding for
pivot-optionsandpivot-value. Using[attr.pivot-options]or[attr.pivot-value]serializes the value to a string with mismatched quotes,JSON.parsefails silently, and the component receives[]. Bind directly to the Lit property instead:checkboxOptions = [
{ label: 'Option A', value: 'a' },
{ label: 'Option B', value: 'b' },
];
checkedValues: string[] = [];
onCheckboxChange(event: CustomEvent<{ values: string[] }>) {
this.checkedValues = event.detail.values;
}<pivot-checkbox
[attr.pivot-name]="name"
.pivotOptions="checkboxOptions"
.pivotValue="checkedValues"
(pivot-checkbox-change)="onCheckboxChange($event)"
></pivot-checkbox>For options that are computed or loaded asynchronously, set the property directly on the element via
@ViewChild:@ViewChild('checkboxRef') checkboxRef!: ElementRef<HTMLElement>;
ngAfterViewInit() {
(this.checkboxRef.nativeElement as any).pivotOptions = this.checkboxOptions;
}Both approaches require
CUSTOM_ELEMENTS_SCHEMAin the Angular component to suppress unknown-property errors.
Companion form fields per option (CheckboxOption)
Each entry in pivotOptions is a CheckboxOption:
interface CheckboxOption {
label: string; // Display text rendered next to the input
value: string; // Value submitted/matched for selection state
showInputField?: boolean | string; // When truthy, renders a pivot-input below this option's label
showTextAreaField?: boolean | string; // When truthy, renders a pivot-text-area below this option's label
showDateField?: boolean | string; // When truthy, renders a pivot-date below this option's label
placeholder?: string; // Placeholder text for the accompanying pivot-input or pivot-text-area, if either is set
maxLength?: number; // Character limit passed to the accompanying pivot-text-area, if showTextAreaField is set
textAreaRows?: number; // Row count passed to the accompanying pivot-text-area, if showTextAreaField is set
minDate?: string; // Earliest selectable date passed to the accompanying pivot-date, if showDateField is set
maxDate?: string; // Latest selectable date passed to the accompanying pivot-date, if showDateField is set
step?: string; // Step interval (in days) passed to the accompanying pivot-date, if showDateField is set
}Set exactly one of showInputField, showTextAreaField, or showDateField (truthy — true or any non-empty string) to render a companion form control below that option’s label:
showInputFieldrenders apivot-input. Useplaceholderto provide a format hint inside the input.showTextAreaFieldrenders apivot-text-area. Useplaceholderfor a format hint,maxLengthto cap and display a character count, andtextAreaRowsto control its visible height (defaults to4if unset).showDateFieldrenders apivot-date. UseminDate/maxDate(inYYYY-MM-DDformat) to bound the selectable range, andstepto set the picker’s step interval in days.
Every companion control inherits the group’s pivot-name, pivot-error, and pivot-disabled states, and uses the option’s label as its accessible name. When the group is pivot-required, a companion is required only while its option is checked.
When its option is checked, a companion’s non-empty value is submitted as <pivot-name>-<option value> (e.g. animal=other&animal-other=…). An invalid companion (e.g. required and empty) makes the group invalid and blocks form submission.
Note: Only place one of
showInputField,showTextAreaField, orshowDateFieldon the last option in the array. The grid layout positions the companion field after the option row and is not designed to accommodate options that follow it.
Using the field-label-tooltip slot
The field-label-tooltip slot accepts a single pivot-field-label-tooltip element rendered beside the fieldset legend. The fieldset legend itself is rendered by a shared renderFieldLabel helper directly into pivot-checkbox’s own shadow DOM. Before every render, pivot-checkbox checks its own light-DOM children for one with slot="field-label-tooltip", and sets its internal hasFieldLabelTooltip state accordingly — no event listener is involved. When hasFieldLabelTooltip is true, an info icon button is rendered inline with the group label; when no content is slotted, nothing extra is rendered. The slot="field-label-tooltip" attribute is required — a <pivot-field-label-tooltip> child without it is not rendered, and the component logs a console warning naming the element.
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-options='[{ "label": "Design", "value": "design" }]'
>
<pivot-field-label-tooltip pivot-tooltip-popover-header="Why do we ask?">
<pivot-text> We use this to personalize your experience. </pivot-text>
</pivot-field-label-tooltip>
</pivot-checkbox>See the pivot-field-label-tooltip documentation for full usage guidelines on the tooltip’s own content.
Using the pivot-checkbox-change event
pivot-checkbox fires pivot-checkbox-change once per individual checkbox toggle — not once per group render. Each time any single checkbox’s native change event fires, the component updates pivotValue and re-dispatches pivot-checkbox-change with the full, current set of checked values for the whole group (not just the value that was just toggled):
document
.querySelector("pivot-checkbox")
.addEventListener("pivot-checkbox-change", (event) => {
console.log(event.detail.values); // e.g. ["design", "research"]
});The event bubbles and is composed, so it can also be caught by a listener attached higher up the DOM (e.g. on a parent pivot-form-container) without needing to bind to the checkbox element directly.
Form Association
pivot-checkbox sets static formAssociated = true, making it a form-associated custom element that integrates with ElementInternals internally. This means:
- Its checked values are included in
FormDatawhen the parent form is submitted, usingpivot-nameas the key. Multiple checked values produce multiple entries under the same key (e.g.interest=design&interest=research). - Form reset via
<button type="reset">orform.reset()restorespivotValueto the state it had at first render and clears any native validation message currently displayed. - When a parent
<fieldset>or form is disabled, the component disables itself viaformDisabledCallback. pivot-checkboxdefines its owncheckValidity()/reportValidity()methods, so you can validate the element directly without going through the containing form. Both also propagate into the parent form’s validity state, since this component’s validity state is forwarded toElementInternalsviasetValidity()after every update.
Submission value
setFormValue(FormData) is used internally so multiple checked values can be submitted under the same key. The submitted entries match whatever values are in pivotValue at submission time — the display labels are never submitted. When no options are checked, setFormValue(null) is called instead, so the field is treated as a non-successful control and omitted from FormData entirely rather than submitting an empty entry under pivot-name.
Required validation
When pivot-required is set and no options are checked, the component reports valueMissing: true via ElementInternals with the message “Please select at least one option.” This prevents form submission, and the message is rendered below the group (see Validation and Error Display). The native required attribute is not set on the individual <input> elements — group-level validation is handled entirely through ElementInternals, so the group reports one message rather than one per checkbox.
Validation and Error Display
pivot-checkbox intercepts the browser’s invalid event and calls preventDefault() on it, so the browser’s native validation bubble never appears. Instead, the group’s validation message is rendered below the options by pivot-field-helper-message, using the same error icon and styling as pivot-error-text. This happens whenever an invalid event fires for the group — on a blocked form submission, on form.checkValidity() / form.reportValidity(), or on the element’s own checkValidity() / reportValidity().
<form>
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-required
pivot-options='[{ "label": "Design", "value": "design" }, { "label": "Research", "value": "research" }]'
></pivot-checkbox>
<button type="submit">Submit</button>
</form>
<!-- Submitting with nothing checked renders "Please select at least one option."
below the group in Pivot error styling. -->The message is removed as soon as the group becomes valid again (i.e. an option is checked) and when the parent form is reset.
The group is in its error state — error styling on every option, aria-invalid="true", and a has-error attribute on the host — when pivot-error is set, pivot-error-text has a value, or a native validation message is displayed. When both pivot-error-text and a native validation message are present, pivot-error-text is the message shown. The component manages has-error itself; don’t set or remove it manually.
pivot-error and pivot-error-text do not affect the group’s validity — use them to display errors from your own (e.g. server-side) validation.
Methods
checkValidity()
Returns boolean. Checks the current constraint-validation state (kept in sync with ElementInternals after every update) and returns whether the group is currently valid. When the group is invalid, the browser fires an invalid event on the host, and the validation message is rendered inline below the group — see Validation and Error Display.
const checkbox = document.querySelector(
"pivot-checkbox[pivot-name='interest']",
);
checkbox.checkValidity(); // true | falsereportValidity()
Returns boolean. Performs the same validity check as checkValidity(). The browser’s native validation bubble is suppressed; when the group is invalid, the validation message is rendered inline below the group instead, exactly as with checkValidity().
const checkbox = document.querySelector(
"pivot-checkbox[pivot-name='interest']",
);
checkbox.reportValidity(); // renders the validation message inline if invalidBoth methods reflect the same validity state that the containing form’s checkValidity() / reportValidity() aggregate — see Form Association.
CSS Parts
| Part | Element | Description |
|---|---|---|
fieldset |
<fieldset> |
The wrapping fieldset element |
legend |
<legend> |
The fieldset legend (group label) |
option |
<div> wrapping each input/label pair |
Container for one checkbox option row |
input |
<input type="checkbox"> |
Each checkbox input element |
label |
<label> |
Each option’s label element |
Accessibility
pivot-checkbox is built entirely from native HTML form elements — <fieldset>, <legend>, <input type="checkbox">, and <label>. This means the browser and assistive technology handle the core accessible semantics with no additional ARIA required.
- Always provide a meaningful
pivot-fieldset-label. Screen readers announce the legend text as the group label when focus enters any checkbox in the group. - Do not leave
pivot-fieldset-labelempty. An unlabelled<fieldset>provides no context for screen reader users about what the group represents. - Use
pivot-requiredwhen a selection is mandatory so the constraint is communicated to assistive technology via the validation message set onElementInternals. - Keep
pivot-error-textandpivot-helper-textconcise and actionable. They are automatically associated with each checkbox input viaaria-describedby— see Screen Reader Behavior below. - Each
<label>is associated to its input viafor/id, expanding the interactive hit target to include the label text. This benefits all users, especially on touch devices.
ARIA Roles and Attributes
The component relies on native HTML semantics and does not add custom ARIA roles.
| Element | Implicit role | Notes |
|---|---|---|
<fieldset> |
group |
Groups all checkboxes under a common label |
<legend> |
— | Labels the <fieldset> group; announced when focus enters the group |
<input type="checkbox"> |
checkbox |
Carries aria-checked state managed by the browser |
<label> |
— | Associated to each input via for / id; expands the clickable hit area |
aria-invalidis set on each<input type="checkbox">("true"/"false"), reflecting the group’s error state —pivot-error,pivot-error-text, or a displayed native validation message (WCAG 4.1.2).aria-describedbylinks each<input type="checkbox">topivot-field-helper-messagewhenever helper text,pivot-error-text, or a native validation message is present (WCAG 1.3.1, WCAG 4.1.3). The error text is additionally announced immediately viapivot-field-helper-message’s ownrole="alert", not only when a checkbox regains focus — see that component’s README.
Not currently set by the component:
aria-errormessage
Per the WAI-ARIA Authoring Practices Guide, descriptive group text is conventionally associated via aria-describedby on the <fieldset> rather than on each input; this component associates it per-input instead, which still reaches assistive technology as focus moves to any checkbox in the group.
Screen Reader Behavior
Expected behavior with the current implementation:
- When focus enters a checkbox input, screen readers announce the input’s checked state, the associated label text, and the group name (from the
<legend>). - Checking or unchecking a checkbox causes the new checked state to be announced immediately.
- The helper or error message — including a native validation message rendered after a failed submit — is associated with each checkbox input via
aria-describedby, so screen readers announce it as focus moves to any option in the group. Because error messages render withrole="alert", a native validation message is also announced as soon as it appears.
Keyboard Navigation
pivot-checkbox inherits all standard keyboard behavior from native <input type="checkbox"> elements. Unlike radio inputs, each checkbox is independently focusable and togglable.
| Key | Behavior |
|---|---|
Tab |
Moves focus to the next checkbox in the group (each is a tab stop). |
Shift + Tab |
Moves focus to the previous checkbox. |
Space |
Toggles the checked state of the focused checkbox. |
This matches the WAI-ARIA Authoring Practices Guide checkbox keyboard pattern.
Checkbox vs. Radio keyboard behavior: Unlike radio groups — where arrow keys move focus and only one item can be selected — each checkbox in a group is an independent tab stop. Users Tab through each option and use Space to toggle individual items. Do not expect arrow key navigation between checkboxes.
Focus Management
- Focus is fully browser-managed through native checkbox inputs.
- Each
<input type="checkbox">is an independent focusable element in the tab order, unlike radio inputs which share a single tab stop. - The component does not manually manage
tabindexor override focus behavior. - The component relies on the browser’s native focus-visible rendering for checkbox inputs.
- The component sets
delegatesFocus: trueviaPivotBase, so focusing the host element will delegate focus to the first focusable internal element. - When form submission or
reportValidity()fails, focus is not moved to the group — the component cancels theinvalidevent to suppress the native bubble, which also cancels the browser’s built-in focus-on-invalid behavior. If you want the first invalid field focused on submit, handle it in your own code — for example, listen forinvalidon the form in the capture phase (the event does not bubble) and call.focus()on the first host that fires it;delegatesFocusthen moves focus to the first checkbox. The rendered error message is still announced viarole="alert"(WCAG 3.3.1).
Related Components
References
- ARIA Authoring Practices Guide — Checkbox Pattern
- MDN —
<input type="checkbox"> - Carbon Design System — Checkbox Usage
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-fieldset-label |
string |
"" |
Label text rendered inside the `<legend>` element. |
pivot-optional |
boolean |
false |
Presence of attribute means true: <pivot-checkbox pivot-optional> |
pivot-name |
string |
"" |
The `name` attribute shared by all checkbox inputs in the group. Required for correct grouping and form submission behaviour. |
pivot-value |
string[] |
[] |
Array of pre-selected option values. Can be set as a JSON array string attribute or as a JavaScript property. A plain string value is also accepted for single-selection convenience. |
pivot-error |
boolean |
false |
Presence of attribute means true: <pivot-checkbox pivot-error> |
pivot-required |
boolean |
false |
When true, at least one checkbox in the group must be checked for the group to be valid. Enforced via `ElementInternals`, not the native `required` attribute on individual inputs. |
pivot-disabled |
boolean |
false |
When true, all checkbox inputs in the group are disabled. |
pivot-error-text |
string | null |
null |
This will create an attribute: pivot-error-text="value" |
pivot-helper-text |
string | null |
null |
This will create an attribute: pivot-helper-text="value" |
pivot-options |
CheckboxOption[] |
[] |
Array of checkbox options to render inside the fieldset. Each item must supply at least `label` and `value`. Can be set as a JSON string attribute or as a JavaScript property. |
Slots
| Name | Description |
|---|---|
field-label-tooltip |
Optional tooltip content rendered beside the fieldset label |
Events
| Name | Type | Description |
|---|---|---|
pivot-checkbox-change |
CustomEvent |
Fired when any checkbox in the group is toggled. |
CSS Custom Properties
| Name | Description |
|---|---|
--component-field-control-general-gap |
Spacing used for the padding around each option row and between each checkbox input and its label. |
--component-field-label-gap |
Vertical spacing between an option's label row and its companion `pivot-input`/`pivot-text-area`/`pivot-date` field, if rendered. Also the horizontal gap between the fieldset legend's label text and its optional/required indicator or tooltip icon. |
--typography-body-md-size |
Font size for checkbox option labels, the fieldset legend label, and its "(optional)" indicator. |
--typography-body-md-height |
Line height for checkbox option labels, the fieldset legend label, and its "(optional)" indicator. |
--typography-constants-body-family |
Font family for the fieldset legend label and its "(optional)" indicator. |
--typography-icon-md-size |
Size of each checkbox input control. |
--global-color-icons-font-awesome-primary-color |
Accent color for checkbox inputs in the default state. |
--global-color-icons-font-awesome-danger-color |
Accent and icon color used in the error state. |
--global-color-icons-font-awesome-disabled-color |
Accent color used for disabled checkbox inputs. |
--global-color-text-on-light-error-color |
Option label color used in the error state, and the color of the required "*" indicator beside the fieldset legend label. Helper and error message text colors are handled by `pivot-field-helper-message`. |
--global-color-text-on-light-light-color |
Text color of the "(optional)" indicator beside the fieldset legend label. |
--component-field-label-color |
Text color of the fieldset legend label. |
--component-input-field-input-disabled |
Label color used when the component is disabled. |
Basic checkbox group
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Pre-selected single option (pivot-value — plain string)
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-value="engineering"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Pre-selected multiple options (pivot-value — JSON array)
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-value='["design", "research"]'
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Required (pivot-required)
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-required
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Optional (pivot-optional)
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-optional
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Field label tooltip (pivot-field-label-tooltip)
Use a tooltip to surface supplemental context about the group — why you’re collecting the information or how it will be used. The field must be completable without reading the tooltip.
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
>
<pivot-field-label-tooltip
slot="field-label-tooltip"
pivot-tooltip-popover-header="Why we ask"
>
<pivot-text>
We use this to personalize your dashboard and recommend relevant content.
</pivot-text>
</pivot-field-label-tooltip>
</pivot-checkbox>Helper text (pivot-helper-text)
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-helper-text="Select all that apply."
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Error state (pivot-error + pivot-error-text)
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-error
pivot-error-text="Please select at least one area of interest."
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Error state with pre-selected options
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-value='["design"]'
pivot-error
pivot-error-text="One or more selected options are no longer available."
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Error text replaces helper text (both set, error active)
<!-- When pivot-error is active, error text replaces helper text -->
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-error
pivot-error-text="Please select at least one area of interest."
pivot-helper-text="Select all that apply."
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Disabled (pivot-disabled)
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-disabled
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Disabled with pre-selected options
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-value='["design", "research"]'
pivot-disabled
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>Options set via JavaScript property
<pivot-checkbox
id="my-checkbox"
pivot-fieldset-label="Preferred communication channels"
pivot-name="channels"
></pivot-checkbox>
<script>
const checkbox = document.getElementById("my-checkbox");
checkbox.pivotOptions = [
{ label: "Email", value: "email" },
{ label: "SMS", value: "sms" },
{ label: "Push", value: "push" },
{ label: "In-app", value: "in-app" },
];
checkbox.pivotValue = ["email", "push"];
</script>Event: pivot-checkbox-change
<pivot-checkbox
id="checkbox-change-demo"
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" }
]'
></pivot-checkbox>
<script>
document
.getElementById("checkbox-change-demo")
.addEventListener("pivot-checkbox-change", (e) => {
console.log(e.detail.values); // e.g. ["design", "research"]
});
</script>Option with input field (showInputField)
Set showInputField: true on an option to render a pivot-input below that option's label. Use placeholder to provide a format hint inside the input. Only use showInputField on the last option in the array.
<pivot-form-container>
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Let me specify", "value": "Let me specify", "showInputField": true, "placeholder": "Please specify" }
]'
></pivot-checkbox>
</pivot-form-container>Option with text area field (showTextAreaField)
Set showTextAreaField: true on an option to render a pivot-text-area below that option's label. Use placeholder for a format hint and maxLength to cap and display a character count; use textAreaRows to control the visible height. Only use showTextAreaField on the last option in the array.
<pivot-form-container>
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Let me specify", "value": "Let me specify", "showTextAreaField": true, "maxLength": 200, "placeholder": "Please specify" }
]'
></pivot-checkbox>
</pivot-form-container>Option with date field (showDateField)
Set showDateField: true on an option to render a pivot-date below that option's label. Use minDate / maxDate (in YYYY-MM-DD format) to bound the selectable range, and step to set the picker's step interval in days. Only use showDateField on the last option in the array.
<pivot-form-container>
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Let me specify", "value": "Let me specify", "showDateField": true }
]'
></pivot-checkbox>
</pivot-form-container>Required, optional, and tooltip with a companion field
When an option renders a companion pivot-input, pivot-text-area, or pivot-date, the required asterisk, (optional) text, and tooltip appear only on the fieldset legend, not on the companion field.
<pivot-form-container>
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest-required"
pivot-required
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Let me specify", "value": "Let me specify", "showInputField": true, "placeholder": "Please specify" }
]'
>
<pivot-field-label-tooltip
slot="field-label-tooltip"
pivot-tooltip-popover-header="Why we ask"
>
<pivot-text>
We use this to personalize your dashboard and recommend relevant
content.
</pivot-text>
</pivot-field-label-tooltip>
</pivot-checkbox>
<pivot-checkbox
pivot-fieldset-label="Availability"
pivot-name="availability-optional"
pivot-optional
pivot-options='[
{ "label": "Weekdays", "value": "weekdays" },
{ "label": "Weekends", "value": "weekends" },
{ "label": "Specific date", "value": "date", "showDateField": true }
]'
></pivot-checkbox>
</pivot-form-container>Full form example
<pivot-form-container>
<pivot-input
pivot-name="full-name"
pivot-label="Full name"
pivot-type="text"
pivot-required
></pivot-input>
<pivot-checkbox
pivot-fieldset-label="Areas of interest"
pivot-name="interest"
pivot-required
pivot-helper-text="Select all that apply."
pivot-options='[
{ "label": "Design", "value": "design" },
{ "label": "Engineering", "value": "engineering" },
{ "label": "Research", "value": "research" },
{ "label": "Let me specify", "value": "Let me specify", "showInputField": true, "placeholder": "Please specify" }
]'
></pivot-checkbox>
<pivot-button pivot-type="submit">Submit</pivot-button>
<pivot-button pivot-variant="secondary" pivot-type="reset"
>Reset</pivot-button
>
</pivot-form-container>