Primitives
Perform state toggling.
import { Component, signal } from "@angular/core";
import { NgIcon, provideIcons } from "@ng-icons/core";
import { heroCheckMini } from "@ng-icons/heroicons/mini";
import { NgpCheckbox } from "ng-primitives/checkbox";
@Component({
selector: "app-checkbox",
imports: [NgIcon, NgpCheckbox],
providers: [provideIcons({ heroCheckMini })],
styles: `
[ngpCheckbox] {
display: flex;
width: 1.25rem;
height: 1.25rem;
cursor: pointer;
align-items: center;
justify-content: center;
border-radius: 0.25rem;
border: 1px solid var(--ngp-border);
background-color: transparent;
padding: 0;
outline: none;
flex: none;
color: var(--ngp-text-inverse);
font-size: 0.75rem;
}
[ngpCheckbox][data-hover] {
background-color: var(--ngp-background-hover);
}
[ngpCheckbox][data-checked],
[ngpCheckbox][data-indeterminate] {
border-color: var(--ngp-background-inverse);
background-color: var(--ngp-background-inverse);
}
[ngpCheckbox][data-focus-visible] {
outline: 2px solid var(--ngp-focus-ring);
outline-offset: 2px;
}
`,
template: `
<span [(ngpCheckboxChecked)]="checked" ngpCheckbox>
@if (checked()) {
<ng-icon name="heroCheckMini" aria-hidden="true" />
}
</span>
`,
})
export default class CheckboxExample {
/**
* The checked state of the checkbox.
*/
readonly checked = signal(true);
}
Import the Checkbox primitives from ng-primitives/checkbox.
import { NgpCheckbox } from 'ng-primitives/checkbox';
Assemble the checkbox directives in your template.
<span ngpCheckbox [(ngpCheckboxChecked)]="checked">
<ng-icon name="checkmark" aria-hidden="true" />
</span>
Create a reusable component that uses the NgpCheckbox directive.
import { Component, model } from '@angular/core';
import { Checkbox } from './checkbox';
@Component({
selector: 'app-root',
imports: [Checkbox],
template: `
<app-checkbox [(checked)]="checked" />
`,
})
export default class App {
checked = model<boolean>(false);
}
Generate a reusable checkbox component using the Angular CLI.
ng g ng-primitives:primitive checkbox
path: The path at which to create the component file.prefix: The prefix to apply to the generated component selector.componentSuffix: The suffix to apply to the generated component class name.fileSuffix: The suffix to apply to the generated component file name. Defaults to component.exampleStyles: Whether to include example styles in the generated component file. Defaults to true.Here are some additional examples of how to use the Checkbox primitives.
The checkbox automatically integrates with the form field primitives.
import { Component, signal } from "@angular/core";
import { NgIcon, provideIcons } from "@ng-icons/core";
import { heroCheckMini } from "@ng-icons/heroicons/mini";
import { NgpCheckbox } from "ng-primitives/checkbox";
import {
NgpDescription,
NgpFormField,
NgpLabel,
} from "ng-primitives/form-field";
@Component({
selector: "app-checkbox-form-control",
imports: [NgIcon, NgpCheckbox, NgpFormField, NgpLabel, NgpDescription],
providers: [provideIcons({ heroCheckMini })],
styles: `
[ngpFormField] {
display: flex;
column-gap: 0.75rem;
}
[ngpCheckbox] {
display: flex;
width: 1.25rem;
height: 1.25rem;
cursor: pointer;
align-items: center;
justify-content: center;
border-radius: 0.25rem;
border: 1px solid var(--ngp-border);
background-color: transparent;
padding: 0;
outline: none;
flex: none;
}
[ngpCheckbox][data-hover] {
background-color: var(--ngp-background-hover);
}
[ngpCheckbox][data-checked] {
border-color: var(--ngp-background-inverse);
background-color: var(--ngp-background-inverse);
}
[ngpCheckbox][data-focus-visible] {
outline: 2px solid var(--ngp-focus-ring);
outline-offset: 2px;
}
ng-icon {
color: var(--ngp-text-inverse);
font-size: 0.75rem;
}
[ngpLabel] {
display: flex;
flex-direction: column;
row-gap: 0.5rem;
font-weight: 500;
font-size: 14px;
line-height: 14px;
color: var(--ngp-text-primary);
}
[ngpDescription] {
font-size: 12px;
line-height: 16px;
color: var(--ngp-text-secondary);
}
`,
template: `
<div ngpFormField>
<span [(ngpCheckboxChecked)]="checked" ngpCheckbox>
@if (checked()) {
<ng-icon name="heroCheckMini" aria-hidden="true" />
}
</span>
<label ngpLabel>
<p>Enable notifications</p>
<p ngpDescription>Receive notifications when someone follows you.</p>
</label>
</div>
`,
})
export default class CheckboxFormFieldExample {
/**
* The checked state of the checkbox.
*/
readonly checked = signal(true);
}
The following directives are available to import from the ng-primitives/checkbox package:
Apply the `ngpCheckbox` directive to an element to that represents the checkbox, such as a `button`. Defines whether the checkbox is checked.
Defines whether the checkbox is indeterminate.
Whether the checkbox is required.
Defines whether the checkbox is disabled.
The event that is emitted when the checkbox value changes.
The event that is emitted when the indeterminate value changes.
[ngpCheckbox]
| Attribute | Description |
|---|---|
data-checked |
Applied when the checkbox is checked. |
data-indeterminate |
Applied when the checkbox is indeterminate. |
data-disabled |
Applied when the checkbox is disabled. |
data-hover |
Applied when the checkbox is hovered. |
data-focus-visible |
Applied when the checkbox is focused. |
data-press |
Applied when the checkbox is pressed. |
Adheres to the Tri-State Checkbox WAI-ARIA design pattern.
Copyright © 2025 Angular Primitives