Checkbox Ready
Checkboxes are used to let a user choose one or more options from a limited number of options.
Examples #
<duet-checkbox id="duet-checkbox_checked_checkbox" checked label="Checked" value="test"></duet-checkbox>
<script>
(function(){
// Select the above checkbox
var checkbox = document.querySelector("#duet-checkbox_checked_checkbox")
// Listen for changes in the checkbox
checkbox.addEventListener("duetChange", function (e) {
console.log("Change detected in checkbox", e.detail)
})
})()
</script>
<duet-checkbox label="Unchecked"></duet-checkbox>
<duet-checkbox checked disabled label="Disabled"></duet-checkbox>
<duet-checkbox required label="I accept the conditions" error="This is mandatory selection"></duet-checkbox>
<script>
const checkbox = document.querySelector("duet-checkbox");
checkbox.addEventListener("change", () => {
checkbox.error = checkbox.checked ? "" : "This is mandatory selection";
});
</script>
<duet-fieldset label="Choose an option">
<duet-checkbox checked label="Option 1"></duet-checkbox>
<duet-checkbox label="Option 2"></duet-checkbox>
<duet-checkbox label="Option 3"></duet-checkbox>
</duet-fieldset>
<duet-fieldset label="Choose an option">
<duet-checkbox checked label="Option 1"></duet-checkbox>
<duet-link url="https://www.duetds.com">Link text</duet-link>
<duet-spacer size="x-large" direction="vertical"></duet-spacer>
<duet-checkbox label="Option 2"></duet-checkbox>
<duet-link url="https://www.duetds.com">Link text</duet-link>
<duet-spacer size="x-large" direction="vertical"></duet-spacer>
<duet-checkbox label="Option 3"></duet-checkbox>
<duet-link url="https://www.duetds.com">Link text</duet-link>
<duet-spacer size="x-large" direction="vertical"></duet-spacer>
</duet-fieldset>
<duet-fieldset label="Choose an option">
<duet-grid responsive breakpoint="small">
<duet-grid-item margin="none" fill>
<duet-checkbox checked label="Option 1"></duet-checkbox>
</duet-grid-item>
<duet-grid-item margin="none" fill>
<duet-checkbox label="Option 2"></duet-checkbox>
</duet-grid-item>
<duet-grid-item margin="none" fill>
<duet-checkbox label="Option 3"></duet-checkbox>
</duet-grid-item>
</duet-grid>
</duet-fieldset>
<duet-grid direction="horizontal">
<duet-grid-item margin="none">
<duet-checkbox label="Olen tutustunut vakuutuksen ehtoihin,tuoteselosteeseen ja avaintietoihin" label-hidden>
</duet-checkbox>
</duet-grid-item>
<duet-grid-item fill margin="none">
<duet-paragraph margin="none">
Olen tutustunut <duet-link url="#">vakuutuksen ehtoihin</duet-link>,
<duet-link url="#">tuoteselosteeseen</duet-link> ja <duet-link url="#">avaintietoihin</duet-link>.
</duet-paragraph>
</duet-grid-item>
</duet-grid>
Properties #
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
accessibleActiveDescendant | accessible-active-descendant | Indicates the id of a related component’s visually focused element. | string | undefined |
accessibleControls | accessible-controls | Use this prop to add an aria-controls attribute. Use the attribute to indicate the id of a component controlled by this component. | string | undefined |
accessibleDescribedBy | accessible-described-by | Indicates the id of a component that describes the checkbox. | string | undefined |
accessibleDescription | accessible-description | Aria description the button | string | undefined |
accessibleDetails | accessible-details | Aria Details of the component | string | undefined |
accessibleIndex | accessible-index | Control the tabindex of checkbox. In most cases this should never be used! It exists only for Duet’s internal needs. | string | undefined |
accessibleLabelledBy | accessible-labelled-by | String of id's that indicate alternative labels elements | string | undefined |
accessibleLiveError | accessible-live-error | The aria-live attribute for the error message. When the input is validated on blur, use "off", as using "polite" or "assertive" makes the screen reader read the error message twice. When the input is validated on submit, use "polite", as "off" would leave the messages unread by screen readers. Use "assertive" only in those rare cases when "polite" would leave the error message unread by screen readers. | "assertive" | "off" | "polite" | "polite" |
accessibleOwns | accessible-owns | Indicates the id of a component owned by the checkbox. | string | undefined |
accessibleSelected | accessible-selected | Aria selected | string | undefined |
checked | checked | Check state of the checkbox. | boolean | false |
disabled | disabled | Makes the checkbox component disabled. This prevents users from being able to interact with the checkbox, and conveys its inactive state to assistive technologies. | boolean | false |
error | error | Display the checkbox in error state along with an error message (when a required choice has not been made). Note that this should only be used for single checkbox - for multiple checkboxes, wrap them in a fieldset and use the error property on that. | string | "" |
identifier | identifier | Adds a unique identifier for the checkbox. | string | undefined |
label | label | Label for the checkbox | string | "label" |
labelHidden | label-hidden | Visually hide the label, but still show it to screen readers. | boolean | false |
margin | margin | Controls the margin of the component. | "auto" | "none" | "auto" |
name | name | Name of the checkbox. | string | undefined |
required | required | Set whether the input is required or not. Please note that this is required for accessible inputs when the user is required to fill them. When using this property you need to also set “novalidate” attribute to your form element to prevent browser from displaying its own validation errors. | boolean | false |
role | role | Defines a specific role attribute for the input. | string | undefined |
theme | theme | Theme of the checkbox. | "" | "default" | "turva" | "" |
value | value | The value of the checkbox does not mean if it's checked or not, use the checked property for that. | string | undefined |
Events #
Event | Description | Type |
---|---|---|
duetBlur | Emitted when the checkbox loses focus. | CustomEvent<{ originalEvent?: Event; checked: boolean; value: string; component: "duet-checkbox"; }> |
duetChange | Emitted when the checked property has changed. | CustomEvent<{ originalEvent?: Event; checked: boolean; value: string; component: "duet-checkbox"; }> |
duetFocus | Emitted when the checkbox has focus. | CustomEvent<{ originalEvent?: Event; checked: boolean; value: string; component: "duet-checkbox"; }> |
Methods #
setFocus(options?: FocusOptions) => Promise<void>
#
Sets focus on the specified duet-checkbox
. Use this method instead of the global
input.focus()
.
Parameters #
Name | Type | Description |
---|---|---|
options | FocusOptions |
Returns #
Type: Promise<void>
Usage #
This section includes guidelines for designers and developers about the usage of this component in different contexts.
When to use #
- When the user should be able to choose one or more options from a limited number of options.
- For “accepting terms of service” and similar functionality.
- In forms to toggle something on or off.
When not to use #
- When you have more than 10 options to choose from. Consider using select instead if the use case allows it.
Accessibility #
This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. You can find additional information regarding accessibility of this component below.
label
property is always required for accessible checkbox control.labelHidden
property hides the above label visually, but still keeps it accessible for assistive technologies.- You can use
accessibleActiveDescendant
property to indicates the id of a related component’s visually focused element. - Use
accessibleControls
property to add an aria-controls attribute. Use the attribute to indicate the id of a component controlled by this component. - Use
accessibleOwns
property to indicate the id of a component owned by the checkbox. accessibleDescribedBy
property can be used to indicate the id of a component which contains descriptive/help text related to the checkbox.disabled
property makes the checkbox component disabled. This prevents users from being able to interact with the checkbox, and conveys its inactive state to assistive technologies.role
property can be used to define a specific role attribute for the input.
Additional considerations #
- When you need to provide links inside the label, please follow the provided example to make sure these links stay accessible.
Integration
For integration, event and theming guidelines, please see Using Components. This documentation explains how to implement and use Duet’s components across different technologies like Angular, React or Vanilla JavaScript.
Tutorials
Follow these practical tutorials to learn how to build simple page layouts using Duet’s CSS Framework, Web Components and other features:
Building Layouts
TutorialsUsing CLI Tools
TutorialsCreating Custom Patterns
TutorialsServer Side Rendering
TutorialsSharing Prototypes
TutorialsUsage With Markdown
Troubleshooting
If you experience any issues while using a component, please head over to the Support page for more guidelines and help.