From b7399afbf2d1565205862e2a3cc1db7f6bbee67a Mon Sep 17 00:00:00 2001 From: Aaron Pettengill Date: Tue, 18 Jun 2024 09:47:59 -0400 Subject: [PATCH] docs: checkboxes --- apps/docs-v2/app/routes/_docs.input-types.mdx | 87 +++++++++++++++++++ apps/docs-v2/typography.ts | 5 ++ packages/react/src/test/uncontrolled.test.tsx | 50 +++++++++++ 3 files changed, 142 insertions(+) diff --git a/apps/docs-v2/app/routes/_docs.input-types.mdx b/apps/docs-v2/app/routes/_docs.input-types.mdx index 6a746750..eed1e615 100644 --- a/apps/docs-v2/app/routes/_docs.input-types.mdx +++ b/apps/docs-v2/app/routes/_docs.input-types.mdx @@ -9,6 +9,8 @@ it should hopefully "just work" the way you expect. But for completeness, this page is going to cover all the different input types and how they interact with RVF. +--- + ## Common traits ### Types @@ -37,6 +39,11 @@ will _always_ be a `string` (except for `file` inputs) **OR** a `string[]`. - If only one input is in the form for a given field, the value will be a `string`. - If multiple inputs in the form have the same name, the value will be a `string[]`. +If you _are_ using state mode, then the value passed to your validator will be the same value +that you would get out of `form.value("myField")`. + +--- + ## Number inputs ### Setting default values @@ -78,6 +85,86 @@ Unless you're using [state mode](/state-mode), your validator should be able to If you're using state mode, then the value passed to your validator will be the same value that you would get out of `form.value("myField")`. +--- + +## Checkboxes & Checkbox groups + +Checkboxes are pretty versatile. They can be used as a simple boolean flag, +or as a group of checkboxes represented by an array of strings. +And this is all without any extra work or controlled components. + +### Setting default values + +Checkboxes can be set using either a `boolean` or a `string[]` as the default value. +If you use a `string[]`, the checkbox will be checked if the checkbox's `value` prop +is in the array. + +### Observing / setting values + +RVF will keep the value returned from `form.value("myCheckbox")` consistent +with the type you provided as the default value. +If you don't set a default value, then it will return a `boolean`. + +### Validating + +#### Single checkboxes + + + Checkboxes commonly trip people up. + The way checkboxes are represented in `FormData` on form submission is like this: + + - A checked checkbox will be in the FormData as the value of its `value` prop. + - If there is no value prop, then the checkbox will be in the FormData as `"on"`. + - An unchecked checkbox will not be in the FormData at all. + + Even if you used a `boolean` as the default value, you're validator should expect to + receive `"on" | undefined`. + + + + ```tsx + // This will be "on" or undefined + + + // This will be "hello" or undefined + + ``` + + + +#### Checkbox groups + + + Checkbox group add an extra layer of complication here, because there could be more than one value. + RVF handles that like this: + + - If only one checkbox is checked, the value is a `string`. + - If multiple checkboxes are checked, then the value is a `string[]`. + + This means that your validator should expect to receive `undefined | string | string[]`. + If you're using `zod`, you can handle this case easily using + [`repeatable` from `zod-form-data`](https://www.remix-validated-form.io/zod-form-data/api-reference#repeatable). + + + ```tsx + // The value of this group could be + // - A single string ("value1") + // - An array of strings (["value1", "value2"]) + // - undefined + + + + + ``` + + + +--- + ## File inputs diff --git a/apps/docs-v2/typography.ts b/apps/docs-v2/typography.ts index 16d1d859..2f3567f7 100644 --- a/apps/docs-v2/typography.ts +++ b/apps/docs-v2/typography.ts @@ -192,6 +192,11 @@ export default function typographyStyles({ theme }: PluginUtils) { marginTop: theme("spacing.10"), marginBottom: theme("spacing.2"), }, + h4: { + fontWeight: "600", + marginTop: theme("spacing.10"), + marginBottom: theme("spacing.2"), + }, // Media "img, video, figure": { diff --git a/packages/react/src/test/uncontrolled.test.tsx b/packages/react/src/test/uncontrolled.test.tsx index 7486c0b0..4342e7fa 100644 --- a/packages/react/src/test/uncontrolled.test.tsx +++ b/packages/react/src/test/uncontrolled.test.tsx @@ -603,6 +603,7 @@ it("should naturally work with boolean checkboxes", async () => { value="test-value" {...form.field("foo").getInputProps({ type: "checkbox" })} /> + 
{JSON.stringify(form.value("foo"))}