From b8b8100fb9555746bce0a243dd2fd17aac7f94d5 Mon Sep 17 00:00:00 2001
From: Robbert Broersma <git@robbertbroersma.nl>
Date: Sat, 11 May 2024 17:28:37 +0200
Subject: [PATCH] feat: form field checkbox component for React

---
 .changeset/tricky-guests-impress.md           |   5 +
 .../src/FormFieldCheckbox.test.tsx            | 670 ++++++++++++++++++
 .../src/FormFieldCheckbox.tsx                 | 120 ++++
 .../src/css-module/FormFieldCheckbox.tsx      |  12 +
 .../src/css-module/index.ts                   |   2 +
 packages/component-library-react/src/index.ts |   2 +
 .../src/stories/FormFieldCheckbox.stories.tsx | 114 ++-
 7 files changed, 866 insertions(+), 59 deletions(-)
 create mode 100644 .changeset/tricky-guests-impress.md
 create mode 100644 packages/component-library-react/src/FormFieldCheckbox.test.tsx
 create mode 100644 packages/component-library-react/src/FormFieldCheckbox.tsx
 create mode 100644 packages/component-library-react/src/css-module/FormFieldCheckbox.tsx

diff --git a/.changeset/tricky-guests-impress.md b/.changeset/tricky-guests-impress.md
new file mode 100644
index 00000000000..c1a76a691b2
--- /dev/null
+++ b/.changeset/tricky-guests-impress.md
@@ -0,0 +1,5 @@
+---
+"@utrecht/component-library-react": minor
+---
+
+Add `<FormFieldCheckbox>` component.
diff --git a/packages/component-library-react/src/FormFieldCheckbox.test.tsx b/packages/component-library-react/src/FormFieldCheckbox.test.tsx
new file mode 100644
index 00000000000..c7c52414815
--- /dev/null
+++ b/packages/component-library-react/src/FormFieldCheckbox.test.tsx
@@ -0,0 +1,670 @@
+import { render, screen } from '@testing-library/react';
+import { createRef } from 'react';
+import { FormFieldCheckbox } from './FormFieldCheckbox';
+import '@testing-library/jest-dom';
+
+describe('Form field with a checkbox', () => {
+  const defaultProps = {
+    name: 'check',
+    label: 'I agree',
+  };
+
+  it('renders an HTML div element', () => {
+    const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+    const field = container.querySelector('div');
+
+    expect(field).toBeInTheDocument();
+  });
+
+  it('renders a design system BEM class name: utrecht-form-field', () => {
+    const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+    const field = container.querySelector('div');
+
+    expect(field).toHaveClass('utrecht-form-field');
+  });
+
+  it('renders a design system BEM modifier class name: utrecht-form-field--checkbox', () => {
+    const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+    const field = container.querySelector('.utrecht-form-field');
+
+    expect(field).toHaveClass('utrecht-form-field--checkbox');
+  });
+
+  it('displays as CSS block element (or equivalent)', () => {
+    const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+    const field = container.querySelector('div');
+
+    expect(field).toBeVisible();
+    expect(field).not.toHaveStyle({ display: 'inline' });
+    expect(field).not.toHaveStyle({ display: 'inline-block' });
+  });
+
+  it('renders rich text content', () => {
+    const { container } = render(
+      <FormFieldCheckbox {...defaultProps}>
+        <hr />
+      </FormFieldCheckbox>,
+    );
+
+    const richText = container.querySelector('hr');
+
+    expect(richText).toBeInTheDocument();
+  });
+
+  it('can be hidden', () => {
+    const { container } = render(<FormFieldCheckbox {...defaultProps} hidden />);
+
+    const field = container.querySelector('div');
+
+    expect(field).not.toBeVisible();
+  });
+
+  it('can have a custom class name', () => {
+    const { container } = render(<FormFieldCheckbox {...defaultProps} className="invalid" />);
+
+    const field = container.querySelector('div');
+
+    expect(field).toHaveClass('invalid');
+  });
+
+  it('can have a additional class name', () => {
+    const { container } = render(<FormFieldCheckbox {...defaultProps} className="large" />);
+
+    const field = container.querySelector(':only-child');
+
+    expect(field).toHaveClass('large');
+    expect(field).toHaveClass('utrecht-form-field');
+  });
+
+  describe('label', () => {
+    it('renders a design system BEM class name: utrecht-form-field__label', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+      const field = container.querySelector('.utrecht-form-field__label');
+
+      expect(field).toBeInTheDocument();
+    });
+
+    it('renders rich text content', () => {
+      const { container } = render(
+        <FormFieldCheckbox
+          {...defaultProps}
+          label={
+            <>
+              I can speak the <i lang="la">lingua franca</i>
+            </>
+          }
+        />,
+      );
+
+      const richText = container.querySelector('i');
+
+      expect(richText).toBeInTheDocument();
+    });
+
+    it('is associated with the checkbox', () => {
+      render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = screen.getByRole('checkbox', { name: 'I agree' });
+
+      expect(checkbox).toBeInTheDocument();
+    });
+
+    it('can be clicked to toggle the checkbox', () => {
+      const labelRef = createRef<HTMLSpanElement>();
+
+      render(<FormFieldCheckbox {...defaultProps} label={<span ref={labelRef}>I agree</span>} />);
+
+      const checkbox = screen.getByRole('checkbox', { name: 'I agree' });
+
+      expect(checkbox).not.toBeChecked();
+
+      labelRef.current?.click();
+
+      expect(checkbox).toBeChecked();
+
+      labelRef.current?.click();
+
+      expect(checkbox).not.toBeChecked();
+    });
+  });
+
+  describe('description', () => {
+    it('is not rendered by default', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+      const field = container.querySelector('.utrecht-form-field__description');
+
+      expect(field).not.toBeInTheDocument();
+    });
+
+    it('renders a design system BEM class name: utrecht-form-field__description', () => {
+      const { container } = render(
+        <FormFieldCheckbox
+          {...defaultProps}
+          description="Lingua franca is a common language between groups of people."
+        />,
+      );
+
+      const field = container.querySelector('.utrecht-form-field__description');
+
+      expect(field).toBeInTheDocument();
+    });
+
+    it('renders rich text content', () => {
+      const { container } = render(
+        <FormFieldCheckbox
+          {...defaultProps}
+          description={
+            <p>
+              You are <strong>not</strong> required to agree.
+            </p>
+          }
+        />,
+      );
+
+      const richText = container.querySelector('strong');
+
+      expect(richText).toBeInTheDocument();
+    });
+
+    it('is associated with the checkbox', () => {
+      const description = 'Lingua franca is a common language between groups of people.';
+
+      render(<FormFieldCheckbox {...defaultProps} description={description} />);
+
+      const checkbox = screen.getByRole('checkbox', { description });
+
+      expect(checkbox).toBeInTheDocument();
+    });
+  });
+
+  describe('error message', () => {
+    it('is not rendered by default', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+      const field = container.querySelector('.utrecht-form-field__error-message');
+
+      expect(field).not.toBeInTheDocument();
+    });
+
+    it('renders a design system BEM class name: utrecht-form-field__error-message', () => {
+      const { container } = render(
+        <FormFieldCheckbox {...defaultProps} invalid errorMessage="Check this required field to continue." />,
+      );
+
+      const field = container.querySelector('.utrecht-form-field__error-message');
+
+      expect(field).toBeInTheDocument();
+    });
+
+    it('renders rich text content', () => {
+      const { container } = render(
+        <FormFieldCheckbox
+          {...defaultProps}
+          invalid
+          errorMessage={
+            <p>
+              You <strong>required</strong> to agree.
+            </p>
+          }
+        />,
+      );
+
+      const richText = container.querySelector('strong');
+
+      expect(richText).toBeInTheDocument();
+    });
+
+    it('is associated with the checkbox', () => {
+      const errorMessage = 'Check this required field to continue.';
+
+      render(<FormFieldCheckbox {...defaultProps} invalid errorMessage={errorMessage} />);
+
+      const checkbox = screen.getByRole('checkbox', { description: errorMessage });
+
+      expect(checkbox).toBeInTheDocument();
+    });
+  });
+
+  describe('input', () => {
+    it('renders a checkbox role element', () => {
+      render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toBeInTheDocument();
+    });
+
+    it('renders a design system BEM class name: utrecht-form-field__input', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+      const field = container.querySelector('.utrecht-form-field__input');
+
+      expect(field).toBeInTheDocument();
+    });
+
+    it('renders an HTML input type=checkbox element', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = container.querySelector('input[type="checkbox"]');
+
+      expect(checkbox).toBeInTheDocument();
+    });
+
+    // TypeScript definitions do not support `switch` yet
+    /*
+    it.skip('can render a switch role element', () => {
+      render(<FormFieldCheckbox {...defaultProps} switch={true} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toBeInTheDocument();
+    });
+
+    it.skip('can render a HTML switch input', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} switch />);
+
+      const checkbox = container.querySelector('input[type="checkbox"][switch]');
+
+      expect(checkbox).toBeInTheDocument();
+    });
+    */
+  });
+
+  describe('status', () => {
+    it('is not rendered by default', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} />);
+
+      const field = container.querySelector('.utrecht-form-field__status');
+
+      expect(field).not.toBeInTheDocument();
+    });
+
+    it('renders a design system BEM class name: utrecht-form-field__status', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} status="Saving..." />);
+
+      const field = container.querySelector('.utrecht-form-field__status');
+
+      expect(field).toBeInTheDocument();
+    });
+
+    it('renders rich text content', () => {
+      const { container } = render(
+        <FormFieldCheckbox
+          {...defaultProps}
+          status={
+            <p>
+              Saving <strong>failed</strong>. Please try again at a later time.
+            </p>
+          }
+        />,
+      );
+
+      const richText = container.querySelector('strong');
+
+      expect(richText).toBeInTheDocument();
+    });
+  });
+
+  describe('change event', () => {
+    it('can trigger a change event', () => {
+      const handleChange = jest.fn();
+
+      render(<FormFieldCheckbox {...defaultProps} onChange={handleChange} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      checkbox?.click();
+
+      expect(handleChange).toHaveBeenCalled();
+    });
+
+    it('does not trigger a change event when disabled', () => {
+      const handleChange = jest.fn();
+
+      render(<FormFieldCheckbox {...defaultProps} disabled onChange={handleChange} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      checkbox?.click();
+
+      expect(handleChange).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('input event', () => {
+    it('can trigger a input event', () => {
+      const handleInput = jest.fn();
+
+      render(<FormFieldCheckbox {...defaultProps} onInput={handleInput} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      checkbox?.click();
+
+      expect(handleInput).toHaveBeenCalled();
+    });
+
+    it('does not trigger a input event when disabled', () => {
+      const handleInput = jest.fn();
+
+      render(<FormFieldCheckbox {...defaultProps} disabled onInput={handleInput} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      checkbox?.click();
+
+      expect(handleInput).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('focus event', () => {
+    it('can trigger a focus event', async () => {
+      const handleFocus = jest.fn();
+
+      render(<FormFieldCheckbox {...defaultProps} onFocus={handleFocus} />);
+
+      const textbox = screen.getByRole('checkbox');
+
+      expect(handleFocus).not.toHaveBeenCalled();
+
+      textbox?.focus();
+
+      expect(handleFocus).toHaveBeenCalled();
+    });
+
+    it('does not trigger a focus event when disabled', async () => {
+      const handleFocus = jest.fn();
+
+      render(<FormFieldCheckbox {...defaultProps} disabled onFocus={handleFocus} />);
+
+      const textbox = screen.getByRole('checkbox');
+
+      textbox?.focus();
+
+      expect(handleFocus).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('blur event', () => {
+    it('can trigger a blur event', async () => {
+      const handleBlur = jest.fn();
+
+      render(<FormFieldCheckbox {...defaultProps} onBlur={handleBlur} />);
+
+      const textbox = screen.getByRole('checkbox');
+
+      expect(handleBlur).not.toHaveBeenCalled();
+
+      textbox?.focus();
+      textbox?.blur();
+
+      expect(handleBlur).toHaveBeenCalled();
+    });
+
+    it('does not trigger a blur event when disabled', async () => {
+      const handleBlur = jest.fn();
+
+      render(<FormFieldCheckbox {...defaultProps} disabled onBlur={handleBlur} />);
+
+      const textbox = screen.getByRole('checkbox');
+
+      textbox?.focus();
+      textbox?.blur();
+
+      expect(handleBlur).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('checked variant', () => {
+    it('is not checked by default', () => {
+      render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeChecked();
+    });
+
+    it('can have a checked state', () => {
+      render(<FormFieldCheckbox {...defaultProps} defaultChecked />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toBeChecked();
+    });
+
+    it('can have a defaultChecked state (in React)', () => {
+      render(<FormFieldCheckbox {...defaultProps} defaultChecked />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toBeChecked();
+    });
+
+    it('can have a checked state in CSS', () => {
+      const handleChange = () => {};
+      const { container } = render(<FormFieldCheckbox {...defaultProps} defaultChecked onChange={handleChange} />);
+
+      const checkbox = container.querySelector(':checked');
+
+      expect(checkbox).toBeInTheDocument();
+    });
+
+    describe('label', () => {
+      it.skip('renders a design system BEM modifier class name: utrecht-form-label--checked', () => {
+        const { container } = render(<FormFieldCheckbox {...defaultProps} defaultChecked />);
+
+        const checkbox = container.querySelector('.utrecht-form-label--checked');
+
+        expect(checkbox).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe('invalid variant', () => {
+    it('renders a design system BEM modifier class name: utrecht-form-field--invalid', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} invalid />);
+
+      const checkbox = container.querySelector('.utrecht-form-field');
+
+      expect(checkbox).toHaveClass('utrecht-form-field--invalid');
+    });
+
+    it('renders a design system BEM modifier class name: utrecht-checkbox--invalid', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} invalid />);
+
+      const checkbox = container.querySelector('.utrecht-checkbox');
+
+      expect(checkbox).toHaveClass('utrecht-checkbox--invalid');
+    });
+
+    it('is not invalid by default', () => {
+      render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeInvalid();
+    });
+
+    it('omits non-essential invalid attributes when not invalid', () => {
+      render(<FormFieldCheckbox {...defaultProps} invalid={false} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeInvalid();
+      expect(checkbox).not.toHaveAttribute('aria-invalid');
+    });
+
+    it('can have an invalid state', () => {
+      render(<FormFieldCheckbox {...defaultProps} invalid />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toBeInvalid();
+    });
+
+    it('can have a invalid state in CSS for inputRequired', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} inputRequired defaultChecked={false} />);
+
+      const checkbox = container.querySelector(':invalid');
+
+      expect(checkbox).toBeInTheDocument();
+    });
+  });
+
+  describe('disabled variant', () => {
+    it('renders a design system BEM modifier class name', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} disabled />);
+
+      const checkbox = container.querySelector('.utrecht-checkbox');
+
+      expect(checkbox).toHaveClass('utrecht-checkbox--disabled');
+    });
+
+    it('is not disabled by default', () => {
+      render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeDisabled();
+    });
+
+    it('omits non-essential disabled attributes when not disabled', () => {
+      render(<FormFieldCheckbox {...defaultProps} disabled={false} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeDisabled();
+      expect(checkbox).not.toHaveAttribute('aria-disabled');
+      expect(checkbox).not.toHaveAttribute('disabled');
+    });
+
+    it('can have a disabled state', () => {
+      render(<FormFieldCheckbox {...defaultProps} disabled />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toBeDisabled();
+    });
+
+    it('can have a disabled state in CSS', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} disabled />);
+
+      const checkbox = container.querySelector(':disabled');
+
+      expect(checkbox).toBeInTheDocument();
+    });
+  });
+
+  describe('required variant', () => {
+    it('is not required by default', () => {
+      render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeRequired();
+    });
+
+    it('omits non-essential required attributes when not required', () => {
+      render(<FormFieldCheckbox {...defaultProps} required={false} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeRequired();
+      expect(checkbox).not.toHaveAttribute('aria-required');
+      expect(checkbox).not.toHaveAttribute('required');
+    });
+
+    it('can have a required state', () => {
+      render(<FormFieldCheckbox {...defaultProps} required />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toBeRequired();
+    });
+  });
+
+  describe('inputRequired state', () => {
+    it('is not required by default', () => {
+      render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeRequired();
+    });
+
+    it('omits non-essential required attributes when not required', () => {
+      render(<FormFieldCheckbox {...defaultProps} inputRequired={false} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).not.toBeRequired();
+      expect(checkbox).not.toHaveAttribute('aria-required');
+      expect(checkbox).not.toHaveAttribute('required');
+    });
+
+    it('can have a required state', () => {
+      render(<FormFieldCheckbox {...defaultProps} inputRequired />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toBeRequired();
+    });
+
+    it('can have a required state in CSS', () => {
+      const { container } = render(<FormFieldCheckbox {...defaultProps} inputRequired />);
+
+      const checkbox = container.querySelector(':required');
+
+      expect(checkbox).toBeInTheDocument();
+    });
+  });
+
+  describe('indeterminate variant', () => {
+    it.skip('is not indeterminate by default (in the accessibility tree)', () => {});
+
+    it('is not indeterminate by default', () => {
+      render(<FormFieldCheckbox {...defaultProps} />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      // TODO: Find out how to test the indeterminate state
+      expect(checkbox).not.toHaveAttribute('aria-checked', 'mixed');
+    });
+
+    it.skip('can have a indeterminate state (in the accessibility tree)', () => {});
+
+    it('can have a indeterminate state', () => {
+      render(<FormFieldCheckbox {...defaultProps} indeterminate />);
+
+      const checkbox = screen.getByRole('checkbox');
+
+      expect(checkbox).toHaveAttribute('aria-checked', 'mixed');
+    });
+  });
+
+  it('supports ForwardRef in React', () => {
+    const ref = createRef<HTMLDivElement>();
+
+    const { container } = render(<FormFieldCheckbox {...defaultProps} ref={ref} />);
+
+    const div = container.querySelector('div');
+
+    expect(ref.current).toBe(div);
+  });
+
+  it('supports ForwardRef for the form control in React', () => {
+    const inputRef = createRef<HTMLInputElement>();
+
+    const { container } = render(<FormFieldCheckbox {...defaultProps} inputRef={inputRef} />);
+
+    const div = container.querySelector('input');
+
+    expect(inputRef.current).toBe(div);
+  });
+});
diff --git a/packages/component-library-react/src/FormFieldCheckbox.tsx b/packages/component-library-react/src/FormFieldCheckbox.tsx
new file mode 100644
index 00000000000..31ef0377831
--- /dev/null
+++ b/packages/component-library-react/src/FormFieldCheckbox.tsx
@@ -0,0 +1,120 @@
+import clsx from 'clsx';
+import type { ForwardedRef, PropsWithChildren, ReactNode, Ref } from 'react';
+import { forwardRef, useId } from 'react';
+import type { CheckboxProps } from './Checkbox';
+import { Checkbox } from './Checkbox';
+import type { FormFieldProps } from './FormField';
+import { FormField } from './FormField';
+import { FormFieldDescription } from './FormFieldDescription';
+import { FormFieldErrorMessage } from './FormFieldErrorMessage';
+import { FormLabel } from './FormLabel';
+
+export interface FormFieldCheckboxProps
+  extends Omit<FormFieldProps, 'type'>,
+    Pick<
+      CheckboxProps,
+      | 'checked'
+      | 'defaultChecked'
+      | 'defaultValue'
+      | 'disabled'
+      | 'indeterminate'
+      | 'inputRequired'
+      | 'invalid'
+      | 'name'
+      | 'required'
+      | 'value'
+    > {
+  description?: ReactNode;
+  errorMessage?: ReactNode;
+  inputRef?: Ref<HTMLInputElement>;
+  label: ReactNode;
+  status?: ReactNode;
+}
+
+export const FormFieldCheckbox = forwardRef(
+  (
+    {
+      checked,
+      children,
+      defaultChecked,
+      defaultValue,
+      description,
+      disabled,
+      errorMessage,
+      indeterminate,
+      inputRef,
+      inputRequired,
+      invalid,
+      label,
+      name,
+      onBlur,
+      onChange,
+      onFocus,
+      onInput,
+      required,
+      status,
+      value,
+      ...props
+    }: PropsWithChildren<FormFieldCheckboxProps>,
+    ref: ForwardedRef<HTMLDivElement>,
+  ) => {
+    const inputId = useId();
+    const descriptionId = useId();
+    const statusId = useId();
+    const errorMessageId = useId();
+
+    return (
+      <FormField invalid={invalid} type="checkbox" ref={ref} {...props}>
+        <div className="utrecht-form-field__label utrecht-form-field__label--checkbox">
+          <FormLabel type="checkbox" htmlFor={inputId}>
+            <Checkbox
+              aria-describedby={
+                clsx({
+                  [descriptionId]: description,
+                  [errorMessageId]: invalid,
+                  [statusId]: status,
+                }) || undefined
+              }
+              checked={checked}
+              className="utrecht-form-field__input"
+              defaultChecked={defaultChecked}
+              defaultValue={defaultValue}
+              disabled={disabled}
+              id={inputId}
+              indeterminate={indeterminate}
+              ref={inputRef}
+              inputRequired={inputRequired}
+              invalid={invalid}
+              name={name}
+              onBlur={onBlur}
+              onChange={onChange}
+              onFocus={onFocus}
+              onInput={onInput}
+              required={required}
+              value={value}
+            />
+            {label}
+          </FormLabel>
+        </div>
+        {description && (
+          <FormFieldDescription className="utrecht-form-field__description" id={descriptionId}>
+            {description}
+          </FormFieldDescription>
+        )}
+        {invalid && errorMessage && (
+          <FormFieldErrorMessage className="utrecht-form-field__error-message" id={errorMessageId}>
+            {errorMessage}
+          </FormFieldErrorMessage>
+        )}
+        {status && (
+          <div className="utrecht-form-field__status" id={statusId}>
+            {status}
+          </div>
+        )}
+        {children}
+      </FormField>
+    );
+  },
+);
+
+FormFieldCheckbox.displayName = 'FormFieldCheckbox';
diff --git a/packages/component-library-react/src/css-module/FormFieldCheckbox.tsx b/packages/component-library-react/src/css-module/FormFieldCheckbox.tsx
new file mode 100644
index 00000000000..139ddbec44d
--- /dev/null
+++ b/packages/component-library-react/src/css-module/FormFieldCheckbox.tsx
@@ -0,0 +1,12 @@
+/**
+ * @license EUPL-1.2
+ * Copyright (c) 2021 Robbert Broersma
+ */
+
+// Inject CSS from components used in `FormFieldCheckbox`
+import './Checkbox';
+import './FormField';
+import './FormFieldDescription';
+import './FormFieldErrorMessage';
+
+export * from '../FormFieldCheckbox';
diff --git a/packages/component-library-react/src/css-module/index.ts b/packages/component-library-react/src/css-module/index.ts
index 434c053ad94..463acf987f1 100644
--- a/packages/component-library-react/src/css-module/index.ts
+++ b/packages/component-library-react/src/css-module/index.ts
@@ -66,6 +66,8 @@ export type { FigureCaptionProps } from '../FigureCaption';
 export { FigureCaption } from './FigureCaption';
 export type { FormFieldProps } from '../FormField';
 export { FormField } from './FormField';
+export type { FormFieldCheckboxProps } from '../FormFieldCheckbox';
+export { FormFieldCheckbox } from './FormFieldCheckbox';
 export type { FormFieldDescriptionProps } from '../FormFieldDescription';
 export { FormFieldDescription } from './FormFieldDescription';
 export type { FormFieldErrorMessageProps } from '../FormFieldErrorMessage';
diff --git a/packages/component-library-react/src/index.ts b/packages/component-library-react/src/index.ts
index 63ec15dd97f..49442da05a2 100644
--- a/packages/component-library-react/src/index.ts
+++ b/packages/component-library-react/src/index.ts
@@ -73,6 +73,8 @@ export type { FigureCaptionProps } from './FigureCaption';
 export { FigureCaption } from './FigureCaption';
 export type { FormFieldProps } from './FormField';
 export { FormField } from './FormField';
+export type { FormFieldCheckboxProps } from './FormFieldCheckbox';
+export { FormFieldCheckbox } from './FormFieldCheckbox';
 export type { FormFieldDescriptionProps } from './FormFieldDescription';
 export { FormFieldDescription } from './FormFieldDescription';
 export type { FormFieldErrorMessageProps } from './FormFieldErrorMessage';
diff --git a/packages/storybook-react/src/stories/FormFieldCheckbox.stories.tsx b/packages/storybook-react/src/stories/FormFieldCheckbox.stories.tsx
index ef377ce04b4..3743552fa02 100644
--- a/packages/storybook-react/src/stories/FormFieldCheckbox.stories.tsx
+++ b/packages/storybook-react/src/stories/FormFieldCheckbox.stories.tsx
@@ -1,21 +1,23 @@
 import { Meta, StoryObj } from '@storybook/react';
-import {
-  Checkbox,
-  FormField,
-  FormFieldDescription,
-  FormLabel,
-  Paragraph,
-} from '@utrecht/component-library-react/dist/css-module';
+import { FormFieldCheckbox } from '@utrecht/component-library-react/dist/css-module';
 import React from 'react';
 import FormFieldMeta from './FormField.stories';
 
 const storyArgTypes = {
   ...FormFieldMeta.argTypes,
-  checked: {
+  defaultChecked: {
     description: 'Checked',
     control: 'boolean',
     table: {
-      category: 'Story',
+      category: 'API',
+      defaultValue: { summary: false },
+    },
+  },
+  indeterminate: {
+    description: 'Indeterminate',
+    control: 'boolean',
+    table: {
+      category: 'API',
       defaultValue: { summary: false },
     },
   },
@@ -23,7 +25,7 @@ const storyArgTypes = {
     description: 'Required',
     control: 'boolean',
     table: {
-      category: 'Story',
+      category: 'API',
       defaultValue: { summary: false },
     },
   },
@@ -31,7 +33,7 @@ const storyArgTypes = {
     description: 'ID',
     type: { name: 'text', required: true },
     table: {
-      category: 'Story',
+      category: 'DOM',
       defaultValue: { summary: '' },
     },
   },
@@ -39,7 +41,7 @@ const storyArgTypes = {
     description: 'Name',
     control: 'text',
     table: {
-      category: 'Story',
+      category: 'API',
       defaultValue: { summary: '' },
     },
   },
@@ -47,7 +49,7 @@ const storyArgTypes = {
     description: 'Value',
     control: 'text',
     table: {
-      category: 'Story',
+      category: 'API',
       defaultValue: { summary: '' },
     },
   },
@@ -56,85 +58,79 @@ const storyArgTypes = {
     type: { name: 'text', required: true },
     table: {
       defaultValue: { summary: false },
-      category: 'Story',
+      category: 'API',
     },
   },
-  invalidDescription: {
-    name: 'invalidDescription',
+  errorMessage: {
+    name: 'errorMessage',
     description: 'Description for invalid input',
     type: { name: 'text', required: false },
     table: {
       defaultValue: { summary: false },
-      category: 'Story',
+      category: 'API',
     },
   },
   description: {
     description: 'Description',
     type: { name: 'text', required: false },
     table: {
-      category: 'Story',
+      category: 'API',
       defaultValue: { summary: '' },
     },
   },
 };
 
 const meta = {
-  title: 'React Component/Form Field/Checkbox',
-  id: 'react-form-field--checkbox',
-  component: FormField,
+  title: 'React Component/Form Field with checkbox',
+  id: 'react-form-field-checkbox',
+  component: FormFieldCheckbox,
   argTypes: storyArgTypes,
   args: {
-    checked: false,
+    defaultChecked: false,
     description: 'U kunt ons echt vertrouwen!',
     disabled: false,
-    id: '43f471c8-c6f1-4867-bc53-9602c06b8a32',
+    id: '12157f39-9547-45b1-aa4b-e1c9d51fcf24',
+    indeterminate: false,
     invalid: true,
-    invalidDescription: 'U moet akkoord gaan met de algemene voorwaarden, anders kunt u niet verder.',
+    errorMessage: 'U moet akkoord gaan met de algemene voorwaarden, anders kunt u niet verder.',
     label: 'Ik ga akkoord met de algemene voorwaarden',
     name: 'consent',
     value: 'true',
     required: true,
-    type: 'checkbox',
   },
   render: (args) => {
-    const { checked, description, disabled, id, invalid, invalidDescription, label, name, required, value, type } =
-      args;
-    const descriptionId = description ? `${id}-description` : null;
-    const invalidDescriptionId = invalidDescription ? `${id}-invalid-description` : null;
+    const {
+      defaultChecked,
+      description,
+      disabled,
+      id,
+      indeterminate,
+      invalid,
+      errorMessage,
+      label,
+      name,
+      required,
+      value,
+    } = args;
     return (
-      <FormField invalid={invalid} type={type}>
-        <Paragraph className="utrecht-form-field__label utrecht-form-field__label--checkbox">
-          <FormLabel disabled={disabled} type="checkbox" htmlFor={id}>
-            <Checkbox
-              aria-describedby={[descriptionId, invalidDescriptionId].filter(Boolean).join(' ') || null}
-              className="utrecht-form-field__input"
-              defaultChecked={checked}
-              disabled={disabled}
-              id={id}
-              invalid={invalid}
-              required={required}
-              name={name}
-              value={value}
-            />
-            {label}
-          </FormLabel>
-        </Paragraph>
-        {description ? (
-          <FormFieldDescription id={descriptionId} className="utrecht-form-field__description">
-            {description}
-          </FormFieldDescription>
-        ) : undefined}
-        {invalidDescription ? (
-          <FormFieldDescription id={invalidDescriptionId} invalid className="utrecht-form-field__description">
-            {invalidDescription}
-          </FormFieldDescription>
-        ) : undefined}
-      </FormField>
+      <FormFieldCheckbox
+        id={id}
+        defaultChecked={defaultChecked}
+        description={description}
+        disabled={disabled}
+        errorMessage={errorMessage}
+        indeterminate={indeterminate}
+        invalid={invalid}
+        label={label}
+        name={name}
+        required={required}
+        value={value}
+      />
     );
   },
-} satisfies Meta<typeof FormField>;
+} satisfies Meta<typeof FormFieldCheckbox>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const FormFieldCheckbox: Story = {};
+export const FormFieldCheckboxStory: Story = {};