From d56acbe0aad10c11909a28dac863c8a07f30b11f Mon Sep 17 00:00:00 2001 From: Jon Graft <849817+FlyersPh9@users.noreply.github.com> Date: Mon, 27 Mar 2023 18:09:46 -0400 Subject: [PATCH 1/6] Initial push. --- .../src/examples/Checkbox.indeterminate.tsx | 23 ++++++++++ .../website/src/examples/Checkbox.loading.tsx | 16 +++++++ apps/website/src/examples/Checkbox.main.tsx | 13 +++--- .../src/examples/Checkbox.statuses.tsx | 17 ++++++++ .../src/examples/Checkbox.visibility.tsx | 23 ++++++++++ apps/website/src/examples/index.tsx | 4 ++ apps/website/src/pages/docs/checkbox.mdx | 43 ++++++++++++++++--- 7 files changed, 127 insertions(+), 12 deletions(-) create mode 100644 apps/website/src/examples/Checkbox.indeterminate.tsx create mode 100644 apps/website/src/examples/Checkbox.loading.tsx create mode 100644 apps/website/src/examples/Checkbox.statuses.tsx create mode 100644 apps/website/src/examples/Checkbox.visibility.tsx diff --git a/apps/website/src/examples/Checkbox.indeterminate.tsx b/apps/website/src/examples/Checkbox.indeterminate.tsx new file mode 100644 index 00000000000..fdb430ecb39 --- /dev/null +++ b/apps/website/src/examples/Checkbox.indeterminate.tsx @@ -0,0 +1,23 @@ +/*--------------------------------------------------------------------------------------------- + * 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.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..3bbf4283bc9 --- /dev/null +++ b/apps/website/src/examples/Checkbox.visibility.tsx @@ -0,0 +1,23 @@ +/*--------------------------------------------------------------------------------------------- + * 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/index.tsx b/apps/website/src/examples/index.tsx index 8de49416650..cf10ecb5238 100644 --- a/apps/website/src/examples/index.tsx +++ b/apps/website/src/examples/index.tsx @@ -48,6 +48,10 @@ 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 CodeMainExample } from './Code.main'; diff --git a/apps/website/src/pages/docs/checkbox.mdx b/apps/website/src/pages/docs/checkbox.mdx index 88eb17e44cd..fd8e994215a 100644 --- a/apps/website/src/pages/docs/checkbox.mdx +++ b/apps/website/src/pages/docs/checkbox.mdx @@ -9,22 +9,53 @@ 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 + +### 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. -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). +### Statuses + + + + + +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. + +### Visibility + + + + -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. +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. ## Props From 351ebe393cedcb29fec8013d3cd5261ae48a2adc Mon Sep 17 00:00:00 2001 From: Jon Graft <849817+FlyersPh9@users.noreply.github.com> Date: Thu, 30 Mar 2023 10:24:13 -0400 Subject: [PATCH 2/6] Indeterminate checkbox demos actually work. --- .../src/examples/Checkbox.indeterminate.tsx | 47 +++++++++++++++-- .../src/examples/Checkbox.visibility.tsx | 50 +++++++++++++++++-- 2 files changed, 89 insertions(+), 8 deletions(-) diff --git a/apps/website/src/examples/Checkbox.indeterminate.tsx b/apps/website/src/examples/Checkbox.indeterminate.tsx index fdb430ecb39..866c3a59fb3 100644 --- a/apps/website/src/examples/Checkbox.indeterminate.tsx +++ b/apps/website/src/examples/Checkbox.indeterminate.tsx @@ -6,17 +6,56 @@ 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, setAllOptions] = React.useState(false); + const [isIndeterminate, setIsIndeterminate] = React.useState(true); + + React.useEffect(() => { + if (option1 && option2) { + setAllOptions(true); + setIsIndeterminate(false); + return; + } + if (option1 || option2) { + setAllOptions(false); + setIsIndeterminate(true); + } else { + setAllOptions(false); + setIsIndeterminate(false); + } + }, [option1, option2]); + + const onAllChange = (value: boolean) => { + setAllOptions(value); + setIsIndeterminate(false); + 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.visibility.tsx b/apps/website/src/examples/Checkbox.visibility.tsx index 3bbf4283bc9..ce14f68be18 100644 --- a/apps/website/src/examples/Checkbox.visibility.tsx +++ b/apps/website/src/examples/Checkbox.visibility.tsx @@ -6,17 +6,59 @@ 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, setAllOptions] = React.useState(false); + const [isIndeterminate, setIsIndeterminate] = React.useState(true); + + React.useEffect(() => { + if (option1 && option2) { + setAllOptions(true); + setIsIndeterminate(false); + return; + } + if (option1 || option2) { + setAllOptions(false); + setIsIndeterminate(true); + } else { + setAllOptions(false); + setIsIndeterminate(false); + } + }, [option1, option2]); + + const onAllChange = (value: boolean) => { + setAllOptions(value); + setIsIndeterminate(false); + 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' + /> ); From 1d5318c03c6a4d73ad72c74d3f72e66306bb49a2 Mon Sep 17 00:00:00 2001 From: Jon Graft <849817+FlyersPh9@users.noreply.github.com> Date: Thu, 30 Mar 2023 10:35:57 -0400 Subject: [PATCH 3/6] Add Usage section, add input group demo. --- .../src/examples/Checkbox.inputgroup.tsx | 17 ++++++++++ apps/website/src/examples/index.tsx | 1 + apps/website/src/pages/docs/checkbox.mdx | 34 ++++++++++++++----- 3 files changed, 44 insertions(+), 8 deletions(-) create mode 100644 apps/website/src/examples/Checkbox.inputgroup.tsx 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/index.tsx b/apps/website/src/examples/index.tsx index cf10ecb5238..488b72030d0 100644 --- a/apps/website/src/examples/index.tsx +++ b/apps/website/src/examples/index.tsx @@ -52,6 +52,7 @@ export { default as CheckboxIndeterminateExample } from './Checkbox.indeterminat 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 fd8e994215a..789b261ac92 100644 --- a/apps/website/src/pages/docs/checkbox.mdx +++ b/apps/website/src/pages/docs/checkbox.mdx @@ -25,6 +25,32 @@ A checkbox is not interchangeable with a [radio](radio). A radio must have at mi ## 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 often paired with the [input group](inputgroup) which gives many additional options. + ### Indeterminate @@ -49,14 +75,6 @@ If the checkbox is performing an action immediately after being checked, it may 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. -### 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. - ## Props From b68172ae36f130646e2f2aa4148963019460f9c7 Mon Sep 17 00:00:00 2001 From: Jon Graft <849817+FlyersPh9@users.noreply.github.com> Date: Thu, 30 Mar 2023 10:48:27 -0400 Subject: [PATCH 4/6] Update apps/website/src/examples/Checkbox.visibility.tsx Co-authored-by: Mayank <9084735+mayank99@users.noreply.github.com> --- apps/website/src/examples/Checkbox.visibility.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/apps/website/src/examples/Checkbox.visibility.tsx b/apps/website/src/examples/Checkbox.visibility.tsx index ce14f68be18..d2259ffc4c3 100644 --- a/apps/website/src/examples/Checkbox.visibility.tsx +++ b/apps/website/src/examples/Checkbox.visibility.tsx @@ -9,7 +9,8 @@ export default () => { const [option1, setOption1] = React.useState(false); const [option2, setOption2] = React.useState(true); const [allOptions, setAllOptions] = React.useState(false); - const [isIndeterminate, setIsIndeterminate] = React.useState(true); + +const isIndeterminate = !(option1 && option2) && (option1 || option2); React.useEffect(() => { if (option1 && option2) { From f22f42db7c20a4b19b6e408dffa253f6a1ef8142 Mon Sep 17 00:00:00 2001 From: Jon Graft <849817+FlyersPh9@users.noreply.github.com> Date: Thu, 30 Mar 2023 10:51:59 -0400 Subject: [PATCH 5/6] Simplifying indeterminate checkbox demos. --- apps/website/src/examples/Checkbox.indeterminate.tsx | 6 +----- apps/website/src/examples/Checkbox.visibility.tsx | 7 +------ 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/apps/website/src/examples/Checkbox.indeterminate.tsx b/apps/website/src/examples/Checkbox.indeterminate.tsx index 866c3a59fb3..3ac7fded908 100644 --- a/apps/website/src/examples/Checkbox.indeterminate.tsx +++ b/apps/website/src/examples/Checkbox.indeterminate.tsx @@ -9,26 +9,22 @@ export default () => { const [option1, setOption1] = React.useState(false); const [option2, setOption2] = React.useState(true); const [allOptions, setAllOptions] = React.useState(false); - const [isIndeterminate, setIsIndeterminate] = React.useState(true); + const isIndeterminate = !(option1 && option2) && (option1 || option2); React.useEffect(() => { if (option1 && option2) { setAllOptions(true); - setIsIndeterminate(false); return; } if (option1 || option2) { setAllOptions(false); - setIsIndeterminate(true); } else { setAllOptions(false); - setIsIndeterminate(false); } }, [option1, option2]); const onAllChange = (value: boolean) => { setAllOptions(value); - setIsIndeterminate(false); setOption1(value); setOption2(value); }; diff --git a/apps/website/src/examples/Checkbox.visibility.tsx b/apps/website/src/examples/Checkbox.visibility.tsx index d2259ffc4c3..bb2a5acd740 100644 --- a/apps/website/src/examples/Checkbox.visibility.tsx +++ b/apps/website/src/examples/Checkbox.visibility.tsx @@ -9,27 +9,22 @@ export default () => { const [option1, setOption1] = React.useState(false); const [option2, setOption2] = React.useState(true); const [allOptions, setAllOptions] = React.useState(false); - -const isIndeterminate = !(option1 && option2) && (option1 || option2); + const isIndeterminate = !(option1 && option2) && (option1 || option2); React.useEffect(() => { if (option1 && option2) { setAllOptions(true); - setIsIndeterminate(false); return; } if (option1 || option2) { setAllOptions(false); - setIsIndeterminate(true); } else { setAllOptions(false); - setIsIndeterminate(false); } }, [option1, option2]); const onAllChange = (value: boolean) => { setAllOptions(value); - setIsIndeterminate(false); setOption1(value); setOption2(value); }; From d2a68f262a0d2134e0abb1a9a9c204fbf9952be6 Mon Sep 17 00:00:00 2001 From: Jon Graft <849817+FlyersPh9@users.noreply.github.com> Date: Thu, 30 Mar 2023 12:10:53 -0400 Subject: [PATCH 6/6] Simplifying indeterminate checkbox demo. --- .../src/examples/Checkbox.indeterminate.tsx | 15 +-------------- apps/website/src/examples/Checkbox.visibility.tsx | 15 +-------------- 2 files changed, 2 insertions(+), 28 deletions(-) diff --git a/apps/website/src/examples/Checkbox.indeterminate.tsx b/apps/website/src/examples/Checkbox.indeterminate.tsx index 3ac7fded908..07b2832df73 100644 --- a/apps/website/src/examples/Checkbox.indeterminate.tsx +++ b/apps/website/src/examples/Checkbox.indeterminate.tsx @@ -8,23 +8,10 @@ import { Checkbox, Flex } from '@itwin/itwinui-react'; export default () => { const [option1, setOption1] = React.useState(false); const [option2, setOption2] = React.useState(true); - const [allOptions, setAllOptions] = React.useState(false); + const allOptions = option1 && option2; const isIndeterminate = !(option1 && option2) && (option1 || option2); - React.useEffect(() => { - if (option1 && option2) { - setAllOptions(true); - return; - } - if (option1 || option2) { - setAllOptions(false); - } else { - setAllOptions(false); - } - }, [option1, option2]); - const onAllChange = (value: boolean) => { - setAllOptions(value); setOption1(value); setOption2(value); }; diff --git a/apps/website/src/examples/Checkbox.visibility.tsx b/apps/website/src/examples/Checkbox.visibility.tsx index bb2a5acd740..856d9fc12c7 100644 --- a/apps/website/src/examples/Checkbox.visibility.tsx +++ b/apps/website/src/examples/Checkbox.visibility.tsx @@ -8,23 +8,10 @@ import { Checkbox, Flex } from '@itwin/itwinui-react'; export default () => { const [option1, setOption1] = React.useState(false); const [option2, setOption2] = React.useState(true); - const [allOptions, setAllOptions] = React.useState(false); + const allOptions = option1 && option2; const isIndeterminate = !(option1 && option2) && (option1 || option2); - React.useEffect(() => { - if (option1 && option2) { - setAllOptions(true); - return; - } - if (option1 || option2) { - setAllOptions(false); - } else { - setAllOptions(false); - } - }, [option1, option2]); - const onAllChange = (value: boolean) => { - setAllOptions(value); setOption1(value); setOption2(value); };