diff --git a/apps/website/src/examples/Checkbox.indeterminate.tsx b/apps/website/src/examples/Checkbox.indeterminate.tsx
new file mode 100644
index 00000000000..07b2832df73
--- /dev/null
+++ b/apps/website/src/examples/Checkbox.indeterminate.tsx
@@ -0,0 +1,45 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+ const [option1, setOption1] = React.useState(false);
+ const [option2, setOption2] = React.useState(true);
+ const allOptions = option1 && option2;
+ const isIndeterminate = !(option1 && option2) && (option1 || option2);
+
+ const onAllChange = (value: boolean) => {
+ setOption1(value);
+ setOption2(value);
+ };
+
+ return (
+
+ onAllChange(event.target.checked)}
+ indeterminate={isIndeterminate}
+ checked={allOptions}
+ />
+
+ setOption1(event.target.checked)}
+ />
+ setOption2(event.target.checked)}
+ />
+
+
+ );
+};
diff --git a/apps/website/src/examples/Checkbox.inputgroup.tsx b/apps/website/src/examples/Checkbox.inputgroup.tsx
new file mode 100644
index 00000000000..63548190f33
--- /dev/null
+++ b/apps/website/src/examples/Checkbox.inputgroup.tsx
@@ -0,0 +1,17 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, InputGroup } from '@itwin/itwinui-react';
+
+export default () => {
+ return (
+
+
+
+
+
+
+ );
+};
diff --git a/apps/website/src/examples/Checkbox.loading.tsx b/apps/website/src/examples/Checkbox.loading.tsx
new file mode 100644
index 00000000000..5a04f29130c
--- /dev/null
+++ b/apps/website/src/examples/Checkbox.loading.tsx
@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+ return (
+
+
+
+
+
+ );
+};
diff --git a/apps/website/src/examples/Checkbox.main.tsx b/apps/website/src/examples/Checkbox.main.tsx
index d6f2ddb7077..c551199b023 100644
--- a/apps/website/src/examples/Checkbox.main.tsx
+++ b/apps/website/src/examples/Checkbox.main.tsx
@@ -3,14 +3,15 @@
* See LICENSE.md in the project root for license terms and full copyright notice.
*--------------------------------------------------------------------------------------------*/
import * as React from 'react';
-import { Checkbox } from '@itwin/itwinui-react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
export default () => {
return (
- <>
-
-
-
-
+
+
+
+
+
+
);
};
diff --git a/apps/website/src/examples/Checkbox.statuses.tsx b/apps/website/src/examples/Checkbox.statuses.tsx
new file mode 100644
index 00000000000..1f6a164da31
--- /dev/null
+++ b/apps/website/src/examples/Checkbox.statuses.tsx
@@ -0,0 +1,17 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+ return (
+
+
+
+
+
+
+ );
+};
diff --git a/apps/website/src/examples/Checkbox.visibility.tsx b/apps/website/src/examples/Checkbox.visibility.tsx
new file mode 100644
index 00000000000..856d9fc12c7
--- /dev/null
+++ b/apps/website/src/examples/Checkbox.visibility.tsx
@@ -0,0 +1,48 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+ const [option1, setOption1] = React.useState(false);
+ const [option2, setOption2] = React.useState(true);
+ const allOptions = option1 && option2;
+ const isIndeterminate = !(option1 && option2) && (option1 || option2);
+
+ const onAllChange = (value: boolean) => {
+ setOption1(value);
+ setOption2(value);
+ };
+
+ return (
+
+ onAllChange(event.target.checked)}
+ indeterminate={isIndeterminate}
+ checked={allOptions}
+ variant='eyeball'
+ />
+
+ setOption1(event.target.checked)}
+ variant='eyeball'
+ />
+ setOption2(event.target.checked)}
+ variant='eyeball'
+ />
+
+
+ );
+};
diff --git a/apps/website/src/examples/index.tsx b/apps/website/src/examples/index.tsx
index 8de49416650..488b72030d0 100644
--- a/apps/website/src/examples/index.tsx
+++ b/apps/website/src/examples/index.tsx
@@ -48,6 +48,11 @@ export { default as ButtonGroupMainExample } from './ButtonGroup.main';
export { default as CarouselMainExample } from './Carousel.main';
export { default as CheckboxMainExample } from './Checkbox.main';
+export { default as CheckboxIndeterminateExample } from './Checkbox.indeterminate';
+export { default as CheckboxLoadingExample } from './Checkbox.loading';
+export { default as CheckboxStatusesExample } from './Checkbox.statuses';
+export { default as CheckboxVisibilityExample } from './Checkbox.visibility';
+export { default as CheckboxInputGroupExample } from './Checkbox.inputgroup';
export { default as CodeMainExample } from './Code.main';
diff --git a/apps/website/src/pages/docs/checkbox.mdx b/apps/website/src/pages/docs/checkbox.mdx
index 88eb17e44cd..789b261ac92 100644
--- a/apps/website/src/pages/docs/checkbox.mdx
+++ b/apps/website/src/pages/docs/checkbox.mdx
@@ -9,22 +9,71 @@ group: inputs
import PropsTable from '~/components/PropsTable.astro';
import LiveExample from '~/components/LiveExample.astro';
-import Placeholder from '~/components/Placeholder.astro';
import * as AllExamples from '~/examples';
{frontmatter.description}
-
-
-A checkbox (or tickbox) is a form component allowing multiple options selection. It serves a similar purpose than the radio button, the main difference being that radio buttons only permits binary option selection.
+A checkbox is a form component, typically accompanied with a label, allowing for the selection of multiple items. A checkbox can be used for selecting one or more options within a list, or to enable / disable / show / hide a feature within the user interface.
+
+A checkbox should not be confused with a [toggle switch](toggleswitch), which has a similar role but is not appropriate in all scenarios. To learn more about when to use a toggle switch or a checkbox, please read [Checkbox vs Toggle Switch by Saadia Minhas](https://uxplanet.org/checkbox-vs-toggle-switch-7fc6e83f10b8).
+
+A checkbox is not interchangeable with a [radio](radio). A radio must have at minimum 2 choice options and only one option can be checked. A checkbox, however, can have as many or as few items checked, and can be displayed as standalone or within a group of two or more.
+
+## Variants
+
+### Default
+
+
+
+
+
+The default checkboxes are used to turn on and off one or multiple options.
+
+### Visibility
+
+
+
+
+
+Often times checkboxes are used to visibly turn on and off a layer within a view. If the checkboxes are used for visibility you can use the eyeball variant which uses an eyeball icon instead of a checkmark to reinforce that something is being shown or hidden.
+
+## Usage
+
+### With input group
-Checkboxes are usually accompanied by a label. They can be used either for selecting one or more options in a list, or to enable, disable, show, or hide a feature in the UI. It should however not be confused with a toggle switch, which has a similar role but is not appropriate in all settings. To learn more about when to use a toggle switch or a checkbox, please read [Checkbox vs Toggle Switch by Saadia Minhas](https://uxplanet.org/checkbox-vs-toggle-switch-7fc6e83f10b8).
+
+
+
+
+Checkboxes are often paired with the [input group](inputgroup) which gives many additional options.
+
+### Indeterminate
+
+
+
+
+
+When a main option has associated sub-options, parent-child checkboxes are used. They make selecting/unselecting the entirety of a list of options easier if all or neither of them apply to a user’s choice. If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox.
+
+### Loading
+
+
+
+
+
+If the checkbox is performing an action immediately after being checked, it may take the user interface some time before reflecting that change. While waiting for that change to occur you can display a loading checkbox so the user understands that the action taken has yet to be applied.
+
+### Statuses
+
+
+
+
-A checkbox is not interchangeable with a radio button. A radio button must have at minimum 2 choice options, almost always has one option pre-selected, and cannot have several options selected at once. A checkbox, however, can be checked and unchecked at will, and can be displayed as standalone or in a group of two or more.
+If you ever need to display the status or severity of a single checkbox, you can apply a status on the checkbox. Before doing so, consider if using an [input group](inputgroup) with a status message makes more sense.
## Props