From 0f58e63fc84302c0aaf067f6f674a1f1f2084be8 Mon Sep 17 00:00:00 2001
From: Haz
Date: Tue, 23 May 2023 19:54:49 +0200
Subject: [PATCH] Improve checkbox examples (#2456)
This PR improves the current checkbox docs and fixes two related issues:
- The `Checkbox` component now accepts `string[]` as the `value` prop.
This is to conform with the native input prop type. If a string array is
passed, it will be stringified, just like in the native input element.
- Fixed the `clickOnEnter` prop on `Checkbox` not working when rendering
the component as a native input element.
---
.changeset/checkbox-examples-1.md | 6 ++
.changeset/checkbox-examples-2.md | 6 ++
components/checkbox.md | 25 ++++++--
components/group.md | 22 +++++++
examples/checkbox-as-button/readme.md | 43 +++++++++++++-
examples/checkbox-as-button/site-icon.tsx | 20 +++++++
examples/checkbox-as-button/style.css | 3 -
examples/checkbox-controlled/readme.md | 7 ---
examples/checkbox-custom/checkbox.tsx | 48 ++++++++++++++++
examples/checkbox-custom/index.tsx | 22 +------
examples/checkbox-custom/readme.md | 19 +++++++
examples/checkbox-custom/site-icon.tsx | 23 ++++++++
examples/checkbox-custom/style.css | 49 +++++++++++-----
examples/checkbox-custom/test.ts | 17 ++++--
examples/checkbox-group/index.tsx | 23 +++-----
examples/checkbox-group/readme.md | 19 +++++++
examples/checkbox-group/site-icon.tsx | 31 ++++++++++
examples/checkbox-store/readme.md | 7 ---
examples/checkbox/site-icon.tsx | 2 +-
examples/checkbox/style.css | 2 +-
guide/200-styling/readme.md | 11 ++++
.../src/checkbox/checkbox.tsx | 27 ++++++---
.../ariakit-react-core/src/command/command.ts | 24 +++++---
website/app/(main)/[category]/[page]/page.tsx | 57 ++++++++++---------
website/build-pages/config.js | 1 +
25 files changed, 394 insertions(+), 120 deletions(-)
create mode 100644 .changeset/checkbox-examples-1.md
create mode 100644 .changeset/checkbox-examples-2.md
create mode 100644 components/group.md
create mode 100644 examples/checkbox-as-button/site-icon.tsx
delete mode 100644 examples/checkbox-controlled/readme.md
create mode 100644 examples/checkbox-custom/checkbox.tsx
create mode 100644 examples/checkbox-custom/site-icon.tsx
create mode 100644 examples/checkbox-group/site-icon.tsx
delete mode 100644 examples/checkbox-store/readme.md
diff --git a/.changeset/checkbox-examples-1.md b/.changeset/checkbox-examples-1.md
new file mode 100644
index 0000000000..a1c74d49f8
--- /dev/null
+++ b/.changeset/checkbox-examples-1.md
@@ -0,0 +1,6 @@
+---
+"@ariakit/react-core": patch
+"@ariakit/react": patch
+---
+
+The `Checkbox` component now accepts `string[]` as the `value` prop. This is to conform with the native input prop type. If a string array is passed, it will be stringified, just like in the native input element. ([#2456](https://github.com/ariakit/ariakit/pull/2456))
diff --git a/.changeset/checkbox-examples-2.md b/.changeset/checkbox-examples-2.md
new file mode 100644
index 0000000000..ac8fcef8c7
--- /dev/null
+++ b/.changeset/checkbox-examples-2.md
@@ -0,0 +1,6 @@
+---
+"@ariakit/react-core": patch
+"@ariakit/react": patch
+---
+
+Fixed the `clickOnEnter` prop on `Checkbox` not working when rendering the component as a native input element. ([#2456](https://github.com/ariakit/ariakit/pull/2456))
diff --git a/components/checkbox.md b/components/checkbox.md
index 60393102bf..a7c60a1c29 100644
--- a/components/checkbox.md
+++ b/components/checkbox.md
@@ -6,13 +6,15 @@
Example
-## Installation
+## Examples
-```sh
-npm i @ariakit/react
-```
+
-Learn more on the [Getting started](/guide/getting-started) guide.
+- [](/examples/checkbox-as-button)
+- [](/examples/checkbox-custom)
+- [](/examples/checkbox-group)
+
+
## API
@@ -23,3 +25,16 @@ Learn more on the [Getting started](/guide/getting-started) guide.
<CheckboxCheck />
</Checkbox>
+
+## Related components
+
+
diff --git a/examples/checkbox-as-button/readme.md b/examples/checkbox-as-button/readme.md
index ba815ecaf3..496f3f7b7e 100644
--- a/examples/checkbox-as-button/readme.md
+++ b/examples/checkbox-as-button/readme.md
@@ -4,8 +4,39 @@
Rendering a custom Checkbox as a button element in React, while keeping it accessible to screen reader and keyboard users.
+
+## Activating on Enter
+
+By default, native checkbox elements are activated on Space, but not on Enter. The Ariakit `Checkbox` component allows you to control this behavior using the [`clickOnEnter`](/apis/checkbox#clickonenter) and [`clickOnSpace`](/apis/checkbox#clickonspace) props. However, when rendering the `Checkbox` as any non-native input element, the `clickOnEnter` prop will be automatically set to `true`.
+
+## Reading the state
+
+In this example, we're reading the [`value`](/apis/checkbox-store#value) state from the checkbox store to render the button's text. This is done by using the selector form of the [`useState`](/apis/checkbox-store#usestate) hook:
+
+```jsx
+const label = checkbox.useState((state) =>
+ state.value ? "Checked" : "Unchecked"
+);
+```
+
+Learn more about reading the state on the [Component stores](/guide/component-stores#reading-the-state) guide.
+
## Styling
When rendering the `Checkbox` component as a non-native `input` element, the `:checked` pseudo-class is not supported. To style the checked state, use the `aria-checked` attribute selector:
@@ -13,8 +44,18 @@ When rendering the `Checkbox` component as a non-native `input` element, the `:c
```css
.button[aria-checked="true"] {
background-color: hsl(204 100% 40%);
- color: hsl(204, 20%, 100%);
+ color: hsl(204 20% 100%);
}
```
Learn more on the [Styling](/guide/styling) guide.
+
+## Related examples
+
+