diff --git a/docs/angular/src/content/en/components/checkbox.mdx b/docs/angular/src/content/en/components/checkbox.mdx deleted file mode 100644 index db035af6d4..0000000000 --- a/docs/angular/src/content/en/components/checkbox.mdx +++ /dev/null @@ -1,341 +0,0 @@ ---- -title: Angular Checkbox Component – Ignite UI for Angular - MIT license -description: Ignite UI for Angular Checkbox component is a selection control that allows users to make a binary choice for a certain condition. Try it Now -keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Controls, Native Angular Components Library, Angular Checkbox components, Angular Checkbox controls -license: MIT -llms: - description: "Angular Checkbox is an extension of the standard HTML input type checkbox, providing similar functionality, only enhanced with things like animations and Material Design styling." ---- - -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; -import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; -import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; - -# Angular Checkbox Component Overview - -
-Angular Checkbox is an extension of the standard HTML input type checkbox, providing similar functionality, only enhanced with things like animations and Material Design styling. It enables users to choose one or several predefined options, mostly in forms and surveys. - -The Ignite UI for Angular Checkbox component is a selection control that allows users to make a binary choice for a certain condition. It behaves similarly to the native browser checkbox. Some of the features it offers are styling options, themes, checked, unchecked, and indeterminate states, and others. -
- -## Angular Checkbox Example - -See the checkbox in action in the following Angular Checkbox example below. - - - -
- -## Getting Started with Ignite UI for Angular Checkbox - -To get started with the Ignite UI for Angular Checkbox component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: - -```cmd -ng add igniteui-angular -``` - -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. - -The next step is to import the `IgxCheckboxModule` in the **app.module.ts** file: - -```typescript -// app.module.ts - -import { IgxCheckboxModule } from 'igniteui-angular/checkbox'; -// import { IgxCheckboxModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxCheckboxModule], - ... -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the `IgxCheckboxComponent` as a standalone dependency. - -```typescript -// home.component.ts - -import { IgxCheckboxComponent } from 'igniteui-angular/checkbox'; -// import { IgxCheckboxComponent } from '@infragistics/igniteui-angular'; for licensed package - -@Component({ - selector: 'app-home', - template: ` - - Simple checkbox - - `, - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IgxCheckboxComponent] -}) -export class HomeComponent {} -``` - -Now that you have the Ignite UI for Angular Checkbox module or component imported, you can start using the `igx-checkbox` component. - -## Using the Angular Checkbox Component - -To make the checkbox in the demo, add the following code inside the component template: - -```html - - Simple checkbox - -``` - -### Checkbox properties - -Let's enhance the code above by binding the checkbox properties to some data. Say, we have an array of task objects, each having two properties: description and done. You can bind the checkbox component property to the underlying task object done property. Analogically, you can bind the property to description. -Optionally, you can also bind the event and add some custom logic in the provided event handler method. - -```typescript -// tasks.component.ts -@Component({...}) -export class HomeComponent { - public tasks = [ - { done: true, description: 'Research' }, - { done: true, description: 'Implement' }, - { done: false, description: 'Test' } - ]; - - public statusChanged() { - // event handler logic - } -} -``` - -Enhance the component template by adding a checkbox for each task and then setting the corresponding property bindings: - -```html -{/*tasks.component.html*/} - - {{ task.description }} - -``` - -Add some styles: - -```scss -//task.component.scss -:host { - display: flex; - flex-flow: column nowrap; - padding: 16px; -} -igx-checkbox { - margin-top: 16px; -} -``` - -The final result would be something like that: - - -### Label Positioning - -You can position the label using the checkbox's property: - -```html - -``` - -If the is not set, the label will be positioned after the checkbox. - -### Indeterminate Checkbox in Angular - -In addition to the checked and unchecked states, there is a third state a checkbox can be in: **indeterminate**. In this state the checkbox is neither checked, nor unchecked. This is set using the checkbox's property: - -```html - -``` - -We can create an app that has a list of tasks that need to be done and one master checkbox in Angular that's going to be checked only if all the tasks are completed. Let's update the previous sample. Starting with the template: - -```html -{/* app.component.html */} - -All done - - - {{ task.description }} - -``` - -Next, we're going to indent the subtasks, so it's more visual that they are part of the same group. - -```scss -// app.component.scss -:host { - display: flex; - flex-flow: column nowrap; - padding: 16px; -} -igx-checkbox { - margin-top: 16px; -} -igx-checkbox.tasks { - padding-left: 10px; -} -``` - -And finally, we'll create the logic of our application: - -```ts -// app.component.ts -public tasks = [ - { done: true, description: 'Research' }, - { done: true, description: 'Implement' }, - { done: false, description: 'Test' } -]; -public get masterCheckbox() { - return this.tasks.reduce( - (acc, curr, idx, arr) => { - acc.checked = acc.checked && curr.done; - acc.done = curr.done ? acc.done + 1 : acc.done; - acc.indeterminate = acc.done === arr.length ? false : !!acc.done; - return acc; - }, - { - checked: true, - done: 0, - indeterminate: false - } - ); -} -public toggleAll() { - if (this.masterCheckbox.checked) { - for (const task of this.tasks) { - task.done = false; - } - } else { - for (const task of this.tasks) { - task.done = true; - } - } -} -``` - -After all that is done, our application should look like this: - - -## Styling - -### Checkbox Theme Property Map - -When you modify a primary property, all related dependent properties are updated automatically: - -| Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$empty-color** | $empty-color-hover | The unchecked border color on hover. | -| | $focus-outline-color (indigo variant only) | The focus outline color for indigo variant. | -| **$fill-color** | $fill-color-hover | The checked border and fill colors on hover. | -| | $tick-color | The checked mark color. | -| | $focus-border-color | The focus border color. | -| | $disabled-indeterminate-color | The disabled border and fill colors in indeterminate state. | -| | $focus-outline-color (bootstrap variant only) | The focus outline color for bootstrap variant. | -| | $focus-outline-color-focused (indigo variant only) | The focus outline color for focused state in indigo variant. | -| **$error-color** | $error-color-hover | The border and fill colors in invalid state on hover. | -| | $focus-outline-color-error | The focus outline color in error state. | -| **$label-color** | $label-color-hover | The text color for the label on hover. | - -> **Note:** The actual results may vary depending on the theme variant. - -To get started with styling the checkbox, we need to import the `index` file, where all the theme functions and the `tokens()` mixin are exported: - -```scss -@use "igniteui-angular/theming" as *; - -// IMPORTANT: Prior to Ignite UI for Angular version 13 use: -// @import '~igniteui-angular/lib/core/styles/themes/index'; -``` - -Then, we create a new theme that extends the and setting parameters to style the checkbox elements. By specifying the `$empty-color` and `$fill-color`, the theme automatically calculates appropriate state colors and contrast foregrounds. You can still override any other parameter with custom values as needed. - -```scss -// in styles.scss -$custom-checkbox-theme: checkbox-theme( - $empty-color: #ecaa53, - $fill-color: #ecaa53, - $border-radius: 5px -); -``` - -Finally, **include** the custom theme in your application: - -```scss -:host { - @include tokens($custom-checkbox-theme); -} -``` - -In the sample below, you can see how using the checkbox component with customized CSS variables allows you to create a design that visually resembles the checkbox used in the [`SAP UI5`](https://ui5.sap.com/#/entity/sap.m.CheckBox/sample/sap.m.sample.CheckBox) design system. - - - -### Styling with Tailwind - -You can style the `checkbox` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. - -Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: - -```scss -@import "tailwindcss"; -... -@use 'igniteui-theming/tailwind/utilities/material.css'; -``` - -The utility file includes both `light` and `dark` theme variants. - -- Use `light-*` classes for the light theme. -- Use `dark-*` classes for the dark theme. -- Append the component name after the prefix, e.g., `light-checkbox`, `dark-checkbox`. - -Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using `arbitrary properties`. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). - -You can find the full list of properties in the . The syntax is as follows: - -```html - - Styled checkbox - -``` - - -The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme. - - -At the end your checkbox should look like this: - - - -
- -## API References -
-- -- -- -## Theming Dependencies - -- - -## Additional Resources - -
- -Our community is active and always welcoming to new ideas. - -- [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) -- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) diff --git a/docs/angular/src/content/en/components/themes/roundness.mdx b/docs/angular/src/content/en/components/themes/roundness.mdx index 36eb3f72e4..27c3be2510 100644 --- a/docs/angular/src/content/en/components/themes/roundness.mdx +++ b/docs/angular/src/content/en/components/themes/roundness.mdx @@ -20,7 +20,7 @@ Many Ignite UI components have predefined minimum and maximum border-radius valu When you set `--ig-radius-factor` to 0, the component uses its minimum border-radius and will appear more block-like with sharp corners. When set to 1, the component uses its maximum predefined border-radius and will appear rounded. Here is a list of the components that have predefined minimum and maximum border-radius values and can be modified using the `--ig-radius-factor` variable:
-• [Action Strip](/action-strip) • [Button](/button) • [Button Group](/components/inputs/button-group) • [Calendar](/calendar) • [Card](/card) • [Carousel](/carousel) • [Checkbox](/checkbox) • [Chip](/chip) • [Combo](/combo) • [Date Picker](/date-picker) • [Date Range Picker](/date-range-picker) • [Grid](/grid/grid) • [Input Group](/input-group) • [Linear Progress](/linear-progress) • [List](/list) • [Month Picker](/month-picker) • [Navigation Drawer](/navdrawer) • [Radio](/radio-button) • [Ripple](/ripple) • [Snackbar](/snackbar) • [Switch](/switch) • [Toast](/toast) +• [Action Strip](/action-strip) • [Button](/button) • [Button Group](/components/inputs/button-group) • [Calendar](/calendar) • [Card](/card) • [Carousel](/carousel) • [Checkbox](/components/inputs/checkbox) • [Chip](/chip) • [Combo](/combo) • [Date Picker](/date-picker) • [Date Range Picker](/date-range-picker) • [Grid](/grid/grid) • [Input Group](/input-group) • [Linear Progress](/linear-progress) • [List](/list) • [Month Picker](/month-picker) • [Navigation Drawer](/navdrawer) • [Radio](/radio-button) • [Ripple](/ripple) • [Snackbar](/snackbar) • [Switch](/switch) • [Toast](/toast) ## Usage diff --git a/docs/angular/src/content/en/components/toc.json b/docs/angular/src/content/en/components/toc.json index cee884ad7d..fe7947a00e 100644 --- a/docs/angular/src/content/en/components/toc.json +++ b/docs/angular/src/content/en/components/toc.json @@ -1963,7 +1963,7 @@ }, { "name": "Checkbox", - "href": "checkbox.mdx" + "href": "inputs/checkbox.mdx" }, { "name": "Switch", diff --git a/docs/angular/src/content/en/grids_templates/cell-editing.mdx b/docs/angular/src/content/en/grids_templates/cell-editing.mdx index 29224aa1fe..4f84adff64 100644 --- a/docs/angular/src/content/en/grids_templates/cell-editing.mdx +++ b/docs/angular/src/content/en/grids_templates/cell-editing.mdx @@ -633,7 +633,7 @@ igx-hierarchical-grid { ### Demo -In addition to the steps above, we can also style the controls that are used for the cells' editing templates: [`input-group`](/input-group#styling), [`datepicker`](/date-picker#styling) & [`checkbox`](/checkbox#styling) +In addition to the steps above, we can also style the controls that are used for the cells' editing templates: [`input-group`](/input-group#styling), [`datepicker`](/date-picker#styling) & [`checkbox`](/components/inputs/checkbox#styling) diff --git a/docs/angular/src/content/en/images/anatomy-content-light/checkbox-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/checkbox-lt-a.png new file mode 100644 index 0000000000..91d4f74896 Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/checkbox-lt-a.png differ diff --git a/docs/angular/src/content/en/images/checkbox/checkbox-do-not.png b/docs/angular/src/content/en/images/checkbox/checkbox-do-not.png new file mode 100644 index 0000000000..4277a50a9f Binary files /dev/null and b/docs/angular/src/content/en/images/checkbox/checkbox-do-not.png differ diff --git a/docs/angular/src/content/en/images/checkbox/checkbox-do.png b/docs/angular/src/content/en/images/checkbox/checkbox-do.png new file mode 100644 index 0000000000..4cb9fa644d Binary files /dev/null and b/docs/angular/src/content/en/images/checkbox/checkbox-do.png differ diff --git a/docs/xplat/src/assets/images/checkbox/checkbox-do-not.png b/docs/xplat/src/assets/images/checkbox/checkbox-do-not.png new file mode 100644 index 0000000000..4277a50a9f Binary files /dev/null and b/docs/xplat/src/assets/images/checkbox/checkbox-do-not.png differ diff --git a/docs/xplat/src/assets/images/checkbox/checkbox-do.png b/docs/xplat/src/assets/images/checkbox/checkbox-do.png new file mode 100644 index 0000000000..4cb9fa644d Binary files /dev/null and b/docs/xplat/src/assets/images/checkbox/checkbox-do.png differ diff --git a/docs/xplat/src/content/en/components/grids/_shared/cell-editing.mdx b/docs/xplat/src/content/en/components/grids/_shared/cell-editing.mdx index 7d017006a2..882c559f0d 100644 --- a/docs/xplat/src/content/en/components/grids/_shared/cell-editing.mdx +++ b/docs/xplat/src/content/en/components/grids/_shared/cell-editing.mdx @@ -1509,7 +1509,7 @@ This way, due to {Platform}'s [ViewEncapsulation](https://angular.io/api/core/Co ### Styling Demo -In addition to the steps above, we can also style the controls that are used for the cells' editing templates: [igx-input-group](../input-group.mdx#styling), [igx-datepicker](../date-picker.mdx#styling) & [igx-checkbox](../checkbox.mdx#styling) +In addition to the steps above, we can also style the controls that are used for the cells' editing templates: [igx-input-group](../input-group.mdx#styling), [igx-datepicker](../date-picker.mdx#styling) & [igx-checkbox](/components/inputs/checkbox#styling) diff --git a/docs/xplat/src/content/en/components/inputs/checkbox.mdx b/docs/xplat/src/content/en/components/inputs/checkbox.mdx index 112a76211a..6fedfa9e2d 100644 --- a/docs/xplat/src/content/en/components/inputs/checkbox.mdx +++ b/docs/xplat/src/content/en/components/inputs/checkbox.mdx @@ -1,8 +1,10 @@ --- -title: "{Platform} Checkbox Component | {ProductName}" -description: Learn how to use the {Platform} Checkbox Component to add checkboxes and enable checked, unchecked or indeterminate state for end-users. +title: "Checkbox Component" +description: "The {Platform} Checkbox lets users select, clear, or set an indeterminate option in forms and interactive interfaces." keywords: "{ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} Checkbox components, {Platform} Checkbox controls" license: MIT +last_updated: "2026-08-25" +relatedComponents: [Switch] mentionedTypes: ["Checkbox", "Form"] llms: description: "The {Platform} Checkbox is a component that lets you add checkboxes to your {Platform} apps." @@ -11,33 +13,84 @@ import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro' import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import { Image } from 'astro:assets'; +import checkboxAnatomy from '@xplat-images/anatomy-content-light/checkbox-lt-a.png'; +import checkboxDo from '@xplat-images/checkbox/checkbox-do.png'; +import checkboxDoNot from '@xplat-images/checkbox/checkbox-do-not.png'; -# {Platform} Checkbox Overview +# Checkbox Component The {Platform} Checkbox is a component that lets you add checkboxes to your {Platform} apps. It behaves as a standard HTML checkbox, enabling users to select basic checked and unchecked states or an additional indeterminate state. You also get full control over the styling of the {Platform} checkbox component and ability to use it with forms. -## Checkbox Example +## Live Demo + + + + + + + + + +## Anatomy -## Usage +The {Platform} Checkbox renders a selectable control with an optional label. -At its core, the allows for a choice between selected/unselected state. The default styling is done according to the selection controls specification in the Material Design guidelines. + + + +1. Checkbox Indicator: indicates the current state. By default it is unselected. Could be before or after the label
+2. Label (optional): specifies the target data available for selection and deselection + +The {Platform} Checkbox consists of an indicator and optional label content. Set the label position when the label should appear before or after the indicator. + +```text +Checkbox +├── Checkbox Indicator +└── Label (optional) +``` + +## Getting Started + +To use the {Platform} Checkbox, follow the [{ProductName} Getting Started](../general-getting-started.mdx) topic for the basic project setup, then install or register the component for your target platform. +### Prerequisites and Version Compatibility -First, you need to install the {ProductName} by running the following command: +Use a supported version of the {ProductName} package for your target framework. Keep the framework package, the Checkbox package, and the theme package on the same release version. + + + + +Using the **{PackageWebComponents}** package, install the package before importing and registering the Checkbox: ```cmd npm install {PackageWebComponents} ``` -You will then need to import the , its necessary CSS, and register its module, like so: +Then import the , its theme CSS, and register the component module: ```ts import { defineComponents, IgcCheckboxComponent } from "igniteui-webcomponents"; @@ -46,23 +99,17 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; defineComponents(IgcCheckboxComponent); ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.mdx) topic. - - - - - -First, you need to the install the corresponding {ProductName} npm package by running the following command: +Using the **{PackageReact}** package, install the package before importing the Checkbox wrapper: ```cmd npm install igniteui-react ``` -You will then need to import the and its necessary CSS, like so: +Then import the React Checkbox wrapper and the theme CSS: ```tsx import { IgrCheckbox } from 'igniteui-react'; @@ -75,9 +122,7 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; - - -Before using the , you need to register it as follows: +Using the **{PackageBlazor}** package, register the Checkbox module before rendering the component: ```csharp // in Program.cs file @@ -85,7 +130,7 @@ Before using the , you need to register it builder.Services.AddIgniteUIBlazor(typeof(IgbCheckboxModule)); ``` -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Then link the theme CSS file in **wwwroot/index.html** for a **Blazor WebAssembly** project or in **Pages/_Host.cshtml** for a **Blazor Server** project: ```razor @@ -94,9 +139,25 @@ You will also need to link an additional CSS file to apply the styling to the + +Using the **igniteui-angular** package, install the package and import the Checkbox component: -The simplest way to start using the is as follows: +```cmd +npm install igniteui-angular +``` + +```ts +import { IgxCheckboxComponent } from 'igniteui-angular/checkbox'; +``` + +Add `IgxCheckboxComponent` to the component `imports` collection, then use the `igx-checkbox` element in your template. + + + + + +After registration, render the with the platform-specific element or wrapper: @@ -122,22 +183,41 @@ The simplest way to start using the is as + + +```html + +``` + + + + The component doesn't work with the standard `
` element. Use `Form` instead. + + +## Usage -## Examples +At its core, the lets users choose between selected and unselected states, with support for an indeterminate state when an option represents a partial selection. -### Label -To provide a meaningful label for the checkbox, simply place some text between the opening and closing tags: +The following example shows the basic Checkbox configuration. To provide a meaningful label for the checkbox, simply place some text between the opening and closing tags: + + + +```html +Accept terms +``` + + ```tsx -Label +Accept terms ``` @@ -145,7 +225,7 @@ To provide a meaningful label for the checkbox, simply place some text between t ```html -Label +Accept terms ``` @@ -153,11 +233,14 @@ To provide a meaningful label for the checkbox, simply place some text between t ```razor -Label +Accept terms ``` + +### Label + You can specify if the label should be positioned before or after the checkbox toggle by setting the attribute of the checkbox. Allowed values are `before` and `after` (default): @@ -184,6 +267,14 @@ You can specify if the label should be positioned before or after the checkbox t + + +```html +Label +``` + + + The checkbox can also be labelled by elements external to the checkbox. In this case, the user is given full control to position and style the label in accordance with their needs. @@ -215,15 +306,29 @@ The checkbox can also be labelled by elements external to the checkbox. In this - + +```html +Label + +``` + + ### Checked You can use the attribute of the component to determine whether the checkbox should be toggled on or off by default. + + +```html + +``` + + + ```tsx @@ -250,12 +355,17 @@ You can use the +### Indeterminate +You can use the property of the component to set the checkbox's value to neither **true** nor **false**. + -### Indeterminate +```html + +``` -You can use the property of the component to set the checkbox's value to neither **true** nor **false**. + @@ -283,9 +393,6 @@ You can use the - - - ### Required You can use the property to mark the checkbox as required. @@ -314,6 +421,14 @@ You can use the + +```html + +``` + + + ### Invalid You can use the attribute to mark the checkbox as invalid. @@ -342,6 +457,14 @@ You can use the + +```html + +``` + + + ### Disabled You can use the attribute to disable the checkbox. @@ -370,10 +493,15 @@ You can use the + +```html + +``` + + ### Forms @@ -403,35 +531,280 @@ You can use the + + +```html + +``` + + + +### Do/Don't + +**When to use:** Use a Checkbox when users can select one or more independent options. + +**When not to use:** Do not use a Checkbox when the control represents an immediate on/off setting; use a Switch instead. + +
+ + + + + + + + + + + + + +
DoDon't
Checkbox used for selecting an independent optionCheckbox used for an immediate on/off setting
+
+ +## Properties + +The following properties cover the main Checkbox configuration options documented on this page. See the full API reference for the complete generated list. + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `boolean` | `false` | Gets or sets whether the checkbox is selected. | +| | `boolean` | `false` | Gets or sets whether the checkbox is in an indeterminate state. | +| | `ToggleLabelPosition` | `after` | Sets the position of the checkbox label. | +| | `boolean` | `false` | Gets or sets whether the checkbox is required. | +| | `boolean` | `false` | Gets or sets whether the checkbox is invalid. | +| | `boolean` | `false` | Gets or sets whether the checkbox is disabled. | +| | `string` | — | Gets or sets the name used when the checkbox is submitted through `Form`. | +| | `string` | — | Gets or sets the value submitted through `Form`. | + ## Styling -The component exposes four CSS parts which we can use for styling: +The {Platform} Checkbox uses CSS parts and documented styling variables to customize its appearance. + +### Sass Theming + +Use the {ProductName} theme system to style the Checkbox consistently with the rest of your application. Verify the available Sass theme parameters in the API documentation before adding a custom theme. + +### CSS Variables + +Use the following styling properties to customize the Checkbox indicator and selected-state appearance: + + + +| Primary Property | Related Properties | Description | +| --- | --- | --- | +| `$empty-color` | `$empty-color-hover`, `$focus-outline-color` | Unchecked border color and related focus or hover states. | +| `$fill-color` | `$fill-color-hover`, `$tick-color`, `$focus-border-color`, `$disabled-indeterminate-color`, `$focus-outline-color` | Checked border, fill, tick, focus, and disabled-indeterminate colors. | +| `$error-color` | `$error-color-hover`, `$focus-outline-color-error` | Invalid-state border and fill colors. | +| `$label-color` | `$label-color-hover` | Checkbox label color. | + + + + + +| Variable | What it changes | +| --- | --- | +| `--tick-color` | The color of the check icon. | +| `--fill-color` | The background color of the selected checkbox. | -|Name|Description| -|--|--| -| `base` | The base wrapper of the checkbox. | -| `control` | The checkbox input element. | + + +### Style Parts + +Use the following CSS parts to target the Checkbox structure: + +| Part | What it styles | +| --- | --- | +| `base` | The base wrapper of the Checkbox. | +| `control` | The checkbox control element. | | `indicator` | The checkbox indicator icon. | -| `label` | The checkbox label. | +| `label` | The Checkbox label. | + +### Custom Styling + + + +The following selectors customize the Checkbox indicator color and selected-state fill: + +| Selector | Declaration | Effect | +| --- | --- | --- | +| `igc-checkbox::part(indicator)` | `--tick-color` | Changes the check icon color. | +| `igc-checkbox::part(control checked)::after` | `--fill-color` | Changes the selected checkbox background color. | -With this four CSS parts we have full control over the Checkbox styling. ```css igc-checkbox::part(indicator) { --tick-color: var(--ig-secondary-500-contrast); /* check icon color */ } +``` +```css igc-checkbox::part(control checked)::after { --fill-color: var(--ig-secondary-500); /* checkbox background color */ } ``` - + + + +To customize the Checkbox theme, create a custom theme with the desired Sass properties: + +```scss +@use "igniteui-angular/theming" as *; + +$custom-checkbox-theme: checkbox-theme( + $empty-color: #ecaa53, + $fill-color: #ecaa53, + $border-radius: 5px +); +``` + +Then include the custom theme in your application: + +```scss +:host { + @include tokens($custom-checkbox-theme); +} +``` + + + + + + + + + + + +### Styling with Tailwind + +You can style the {Platform} Checkbox with the custom Tailwind utility classes from `igniteui-theming`. Make sure to [set up Tailwind](/themes/tailwind) first, then import the Ignite UI utilities in your global stylesheet: + +```css +@import "tailwindcss"; +@import "igniteui-theming/tailwind/utilities/material.css"; +``` + + + +```jsx + +``` + + + + + +```html + +``` + + + + + +```razor + +``` + + + + + +```html + +``` + + + +The exclamation mark (`!`) gives the Tailwind utility precedence over the Checkbox's default theme styles. + + + + + + + + + + + + + +## Accessibility + +The {Platform} Checkbox provides a selectable control with a label and state that must remain understandable for keyboard and assistive technology users. + +### Keyboard Interaction + +Use the keyboard interaction provided by the Checkbox and verify the focus and state-change behavior for the target platform. + +| Interaction | Expected behavior | +| --- | --- | +| Keyboard focus | The user can move focus to the Checkbox according to the platform's focus behavior. | +| Space key | The focused Checkbox changes its checked state. | +| Indeterminate state | The Checkbox exposes its current state when the indeterminate state is enabled. | + +### Screen Readers / ARIA + +Provide meaningful label content for every Checkbox so assistive technology users can identify its purpose. When the label is outside the component, reference it with the appropriate ARIA labelling attribute and verify the announcement in the target platform. + +The checked, unchecked, required, invalid, disabled, and indeterminate states must remain available to assistive technology through the component's supported semantics. Verify the rendered announcement against the platform API documentation. + +### Accessibility Compliance + +Verify the rendered {Platform} Checkbox against the accessibility requirements of the application. Check the accessible name, focus visibility, keyboard interaction, checked state, indeterminate state, required state, invalid state, and disabled state in the target framework. + +## Troubleshooting + +The {Platform} Checkbox troubleshooting guidance follows a problem, cause, and fix format for common form and state issues. + +### Why does the Checkbox not submit with my form? + +The Checkbox uses the documented {ProductName} `Form` integration rather than the standard HTML `` element. Use `Form`, then configure unique `name` and `value` properties on the Checkbox. + +### Known Limitations + +The {Platform} Checkbox requires the documented `Form` integration for form submission rather than a standard HTML `` element. + +- The Checkbox must have a `name` and `value` when its state is submitted through `Form`. +- The Checkbox's label, validation state, and disabled state must be configured separately from form submission. ## API References + +The {Platform} Checkbox API reference provides the complete API surface for the component and its form integration. + + + +## Dependencies + +The {Platform} Checkbox requires the platform package and its theme stylesheet. Form scenarios also require the {ProductName} `Form` integration described in **Getting Started**. + ## Additional Resources +Use the following {Platform} resources for API details and project support: + - [{ProductName} **Forums**]({ForumsLink}) - [{ProductName} **GitHub**]({GithubLink}) + +## Related Components + +The {Platform} Checkbox is intended for selectable form options. Use the following related component when you need an immediate on/off action instead: + +- + +## FAQ + +These frequently asked questions cover common {Platform} Checkbox selection, form, and setup scenarios. + + + + Use the documented {ProductName} `Form` integration and verify the required registration for your target platform. + + + Set the `indeterminate` property to enable the indeterminate state. + + diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json index 5839d7ff38..e9fd67ce5b 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -2448,11 +2448,9 @@ "updated": true }, { - "exclude": [ - "Angular" - ], "name": "Checkbox", - "href": "inputs/checkbox.mdx" + "href": "inputs/checkbox.mdx", + "updated": true }, { "exclude": [