@dhis2-ui/checkbox 10.16.1 → 10.16.3-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2-ui/checkbox",
-    "version": "10.16.1",
+    "version": "10.16.3-alpha.1",
     "description": "UI Checkbox",
     "repository": {
         "type": "git",
@@ -33,15 +33,16 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2-ui/field": "10.16.1",
-        "@dhis2-ui/required": "10.16.1",
-        "@dhis2/ui-constants": "10.16.1",
+        "@dhis2-ui/field": "10.16.3-alpha.1",
+        "@dhis2-ui/required": "10.16.3-alpha.1",
+        "@dhis2/ui-constants": "10.16.3-alpha.1",
         "classnames": "^2.3.1",
         "prop-types": "^15.7.2"
     },
     "files": [
         "build",
-        "types"
+        "types",
+        "src"
     ],
     "devDependencies": {
         "react": "^18.3.1",

package/src/checkbox/__tests__/checkbox.test.js

@@ -0,0 +1,31 @@
+import { render, fireEvent, screen } from '@testing-library/react'
+import React from 'react'
+import { Checkbox } from '../checkbox.js'
+
+describe('<Checkbox />', () => {
+    it('should call the onKeyDown callback when provided', () => {
+        const onKeyDown = jest.fn()
+
+        render(
+            <Checkbox
+                name="foo"
+                value="bar"
+                checked={false}
+                onKeyDown={onKeyDown}
+            />
+        )
+
+        fireEvent.keyDown(screen.getByRole('checkbox'), {
+            key: 'Enter',
+            code: 'Enter',
+            charCode: 13,
+        })
+
+        expect(onKeyDown).toHaveBeenCalledWith(
+            { name: 'foo', value: 'bar', checked: true },
+            expect.objectContaining({})
+        )
+
+        expect(onKeyDown).toHaveBeenCalledTimes(1)
+    })
+})

package/src/checkbox/checkbox-icon.js

@@ -0,0 +1,201 @@
+import { colors } from '@dhis2/ui-constants'
+import PropTypes from 'prop-types'
+import React from 'react'
+import css from 'styled-jsx/css'
+
+const commonStyles = css`
+    svg {
+        display: block;
+        pointer-events: none;
+    }
+    svg .border {
+        fill: ${colors.grey800};
+    }
+    svg .background,
+    svg .indeterminate,
+    svg .checkmark {
+        fill: ${colors.white};
+    }
+
+    svg.checked .background,
+    svg.indeterminate .background {
+        fill: ${colors.teal500};
+    }
+    svg.valid .background {
+        fill: ${colors.blue600};
+    }
+    svg.warning .background {
+        fill: ${colors.yellow700};
+    }
+    svg.error .background {
+        fill: ${colors.red500};
+    }
+
+    svg.checked .border,
+    svg.indeterminate .border {
+        fill: ${colors.teal900};
+    }
+
+    svg:not(.checked) .checkmark,
+    svg:not(.indeterminate) .indeterminate {
+        fill: none;
+    }
+    svg:not(.checked):not(.indeterminate) .background {
+        fill: ${colors.white};
+    }
+`
+
+export function CheckboxRegular({ className }) {
+    return (
+        <svg
+            viewBox="0 0 18 18"
+            xmlns="http://www.w3.org/2000/svg"
+            className={className}
+        >
+            <rect
+                className="background"
+                x="0"
+                y="0"
+                width="18"
+                height="18"
+                rx="3"
+            ></rect>
+            <path
+                d="M15,0 C16.6568542,0 18,1.34314575 18,3 L18,15 C18,16.6568542 16.6568542,18 15,18 L3,18 C1.34314575,18 0,16.6568542 0,15 L0,3 C0,1.34314575 1.34314575,0 3,0 L15,0 Z M15,1 L3,1 C1.9456382,1 1.08183488,1.81587779 1.00548574,2.85073766 L1,3 L1,15 C1,16.0543618 1.81587779,16.9181651 2.85073766,16.9945143 L3,17 L15,17 C16.0543618,17 16.9181651,16.1841222 16.9945143,15.1492623 L17,15 L17,3 C17,1.9456382 16.1841222,1.08183488 15.1492623,1.00548574 L15,1 Z"
+                className="border"
+            ></path>
+            <path
+                d="M4.74451387,8.02852516 C4.39595738,8.11985643 4.12375034,8.39235188 4.03251575,8.74127768 C3.94128115,9.09020348 4.04521722,9.46125864 4.30437605,9.71182782 L7.29823844,12.7078028 C7.68753993,13.0973991 8.31859767,13.0973991 8.70789916,12.7078028 L13.695624,6.71585285 C13.9547828,6.46528367 14.0587189,6.09422851 13.9674843,5.74530271 C13.8762497,5.39637691 13.6040426,5.12388146 13.2554861,5.0325502 C12.9069296,4.94121893 12.5362672,5.04526513 12.2859632,5.30469855 L8.0030688,10.5910713 L5.71403676,8.30067351 C5.46373279,8.0412401 5.09307036,7.9371939 4.74451387,8.02852516 Z"
+                className="checkmark"
+            ></path>
+            <rect
+                className="indeterminate"
+                x="4"
+                y="8"
+                width="10"
+                height="2"
+                rx="1"
+            ></rect>
+            <style jsx>{commonStyles}</style>
+            <style jsx>{`
+                svg {
+                    width: 18px;
+                    height: 18px;
+                }
+
+                svg.disabled .background {
+                    fill: ${colors.grey300};
+                }
+                svg.disabled .border {
+                    fill: ${colors.grey400};
+                }
+
+                svg.valid .border {
+                    fill: ${colors.blue600};
+                }
+                svg.valid.checked .border,
+                svg.valid.indeterminate .border {
+                    fill: ${colors.blue700};
+                }
+
+                svg.warning .border {
+                    fill: ${colors.yellow700};
+                }
+                svg.warning.checked .border,
+                svg.warning.indeterminate .border {
+                    fill: ${colors.yellow800};
+                }
+
+                svg.error .border {
+                    fill: ${colors.red500};
+                }
+                svg.error.checked .border,
+                svg.error.indeterminate .border {
+                    fill: ${colors.red700};
+                }
+            `}</style>
+        </svg>
+    )
+}
+CheckboxRegular.propTypes = {
+    className: PropTypes.string,
+}
+
+export function CheckboxDense({ className }) {
+    return (
+        <svg
+            viewBox="0 0 14 14"
+            xmlns="http://www.w3.org/2000/svg"
+            className={className}
+        >
+            <rect
+                className="background"
+                x="0"
+                y="0"
+                width="14"
+                height="14"
+                rx="2"
+            ></rect>
+            <path
+                d="M2,0 L12,0 C13.1045695,0 14,0.8954305 14,2 L14,12 C14,13.1045695 13.1045695,14 12,14 L2,14 C0.8954305,14 0,13.1045695 0,12 L0,2 C0,0.8954305 0.8954305,0 2,0 Z M2,1 C1.44771525,1 1,1.44771525 1,2 L1,12 C1,12.5522847 1.44771525,13 2,13 L12,13 C12.5522847,13 13,12.5522847 13,12 L13,2 C13,1.44771525 12.5522847,1 12,1 L2,1 Z"
+                className="border"
+            ></path>
+            <path
+                d="M10.3520005,3.30015877 L5.54268293,8.03252726 L3.64634146,6.16652726 L2.28668615,7.5044281 L5.54310367,10.7010587 L11.7145993,4.628307 L10.3520005,3.30015877 Z M5.54268293,9.43547274 L5.61193184,9.36733181 L5.54226219,9.29894127 L5.47309681,9.367 L5.54268293,9.43547274 Z M10.6496329,4.41023392 L10.6495057,4.35652297 L10.5648412,4.35672356 L10.2854007,4.631693 L10.3553166,4.69984123 L10.6496329,4.41023392 Z M3.42891348,7.22439304 L3.35030905,7.22439304 L3.35034135,7.27820863 L3.64634146,7.56947274 L3.71331385,7.5035719 L3.42891348,7.22439304 Z"
+                className="checkmark"
+            ></path>
+            <rect
+                className="indeterminate"
+                x="3"
+                y="6"
+                width="8"
+                height="2"
+            ></rect>
+            <style jsx>{commonStyles}</style>
+            <style jsx>{`
+                svg {
+                    width: 14px;
+                    height: 14px;
+                }
+
+                svg.disabled .background {
+                    fill: ${colors.grey400};
+                }
+                svg.disabled .border {
+                    fill: ${colors.grey400};
+                }
+                svg.disabled.checked .border,
+                svg.disabled.indeterminate .border {
+                    fill: ${colors.grey500};
+                }
+
+                svg.valid .border {
+                    fill: ${colors.blue600};
+                }
+                svg.valid.checked .border,
+                svg.valid.indeterminate .border {
+                    fill: ${colors.blue800};
+                }
+
+                svg.warning .border {
+                    fill: ${colors.yellow700};
+                }
+                svg.warning.checked .border,
+                svg.warning.indeterminate .border {
+                    fill: ${colors.yellow800};
+                }
+
+                svg.error .border {
+                    fill: ${colors.red500};
+                }
+                svg.error.checked .border,
+                svg.error.indeterminate .border {
+                    fill: ${colors.red800};
+                }
+            `}</style>
+        </svg>
+    )
+}
+CheckboxDense.propTypes = {
+    className: PropTypes.string,
+}

package/src/checkbox/checkbox.e2e.stories.js

@@ -0,0 +1,55 @@
+import React from 'react'
+import { Checkbox } from './index.js'
+
+window.onClick = window.Cypress && window.Cypress.cy.stub()
+window.onChange = window.Cypress && window.Cypress.cy.stub()
+window.onBlur = window.Cypress && window.Cypress.cy.stub()
+window.onFocus = window.Cypress && window.Cypress.cy.stub()
+
+export default { title: 'Checkbox' }
+export const WithOnChange = () => (
+    <Checkbox
+        name="Ex"
+        label="Checkbox"
+        value="default"
+        onChange={window.onChange}
+    />
+)
+export const WithInitialFocusAndOnBlur = () => (
+    <Checkbox
+        initialFocus
+        name="Ex"
+        label="Checkbox"
+        value="default"
+        onBlur={window.onBlur}
+    />
+)
+export const WithOnFocus = () => (
+    <Checkbox
+        name="Ex"
+        label="Checkbox"
+        value="default"
+        onFocus={window.onFocus}
+    />
+)
+export const DisabledWithOnClick = () => (
+    <Checkbox
+        name="Ex"
+        label="Checkbox"
+        value="default"
+        disabled
+        onClick={window.onClick}
+    />
+)
+export const WithLabel = () => (
+    <Checkbox name="Ex" label="The label" value="default" />
+)
+export const WithInitialFocus = () => (
+    <Checkbox name="Ex" label="The label" value="default" initialFocus />
+)
+export const IndeterminateProp = () => (
+    <Checkbox name="Ex" label="The label" value="default" indeterminate />
+)
+export const NoIndeterminateProp = () => (
+    <Checkbox name="Ex" label="The label" value="default" />
+)

package/src/checkbox/checkbox.js

@@ -0,0 +1,214 @@
+import { mutuallyExclusive } from '@dhis2/prop-types'
+import { colors, spacers, theme, sharedPropTypes } from '@dhis2/ui-constants'
+import cx from 'classnames'
+import PropTypes from 'prop-types'
+import React, { Component, createRef } from 'react'
+import { CheckboxRegular, CheckboxDense } from './checkbox-icon.js'
+
+class Checkbox extends Component {
+    ref = createRef()
+
+    componentDidMount() {
+        if (this.props.initialFocus) {
+            this.ref.current.focus()
+        }
+
+        this.setIndeterminate(this.props.indeterminate)
+    }
+
+    componentDidUpdate(prevProps) {
+        if (prevProps.indeterminate !== this.props.indeterminate) {
+            this.setIndeterminate(this.props.indeterminate)
+        }
+    }
+
+    setIndeterminate(indeterminate) {
+        this.ref.current.indeterminate = indeterminate
+    }
+
+    handleChange = (e) => {
+        if (this.props.onChange) {
+            this.props.onChange(this.createHandlerPayload(), e)
+        }
+    }
+
+    handleBlur = (e) => {
+        if (this.props.onBlur) {
+            this.props.onBlur(this.createHandlerPayload(), e)
+        }
+    }
+
+    handleFocus = (e) => {
+        if (this.props.onFocus) {
+            this.props.onFocus(this.createHandlerPayload(), e)
+        }
+    }
+
+    handleKeyDown = (e) => {
+        if (this.props.onKeyDown) {
+            this.props.onKeyDown(this.createHandlerPayload(), e)
+        }
+    }
+
+    createHandlerPayload() {
+        return {
+            value: this.props.value,
+            name: this.props.name,
+            checked: !this.props.checked,
+        }
+    }
+
+    static defaultProps = {
+        checked: false,
+        indeterminate: false,
+        dataTest: 'dhis2-uicore-checkbox',
+    }
+
+    render() {
+        const {
+            checked = false,
+            indeterminate = false,
+            className,
+            disabled,
+            error,
+            label,
+            name,
+            tabIndex,
+            valid,
+            value,
+            warning,
+            dense,
+            dataTest = 'dhis2-uicore-checkbox',
+        } = this.props
+
+        const classes = cx({
+            checked,
+            indeterminate,
+            disabled,
+            valid,
+            error,
+            warning,
+        })
+
+        return (
+            <label
+                className={cx(className, {
+                    disabled,
+                    dense,
+                })}
+                data-test={dataTest}
+            >
+                <input
+                    type="checkbox"
+                    ref={this.ref}
+                    name={name}
+                    value={value}
+                    checked={checked}
+                    disabled={disabled}
+                    tabIndex={tabIndex}
+                    onChange={this.handleChange}
+                    onFocus={this.handleFocus}
+                    onKeyDown={this.handleKeyDown}
+                    onBlur={this.handleBlur}
+                />
+
+                <div className={cx('icon', { dense })}>
+                    {dense ? (
+                        <CheckboxDense className={classes} />
+                    ) : (
+                        <CheckboxRegular className={classes} />
+                    )}
+                </div>
+
+                {label}
+
+                <style jsx>{`
+                    label {
+                        display: flex;
+                        position: relative;
+                        flex-direction: row;
+                        align-items: center;
+                        justify-content: flex-start;
+                        cursor: pointer;
+                        color: ${colors.grey900};
+                        font-size: 14px;
+                        line-height: 19px;
+                    }
+
+                    label.dense {
+                        font-size: 14px;
+                        line-height: 16px;
+                    }
+
+                    label.disabled {
+                        cursor: not-allowed;
+                        color: ${theme.disabled};
+                    }
+
+                    input {
+                        opacity: 0;
+                        position: absolute;
+                        /* The same size as the icon */
+                        height: 18px;
+                        width: 18px;
+                        /* The same offset as the icon, 2px border, 1px padding */
+                        inset-inline-start: 3px;
+                    }
+
+                    label.dense input {
+                        /* The same size as the dense icon */
+                        height: 14px;
+                        width: 14px;
+                    }
+
+                    .icon {
+                        user-select: none;
+                        margin-inline-end: ${spacers.dp4};
+                        border: 2px solid transparent;
+                        padding: 1px;
+                        border-radius: 5px;
+                    }
+
+                    label.dense .icon {
+                        margin-inline-end: 3px;
+                        border-radius: 4px;
+                    }
+
+                    input:focus + .icon {
+                        outline: 3px solid ${theme.focus};
+                        outline-offset: -3px;
+                    }
+                `}</style>
+            </label>
+        )
+    }
+}
+
+const uniqueOnStatePropType = mutuallyExclusive(
+    ['checked', 'indeterminate'],
+    PropTypes.bool
+)
+
+Checkbox.propTypes = {
+    checked: uniqueOnStatePropType,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    dense: PropTypes.bool,
+    disabled: PropTypes.bool,
+    error: sharedPropTypes.statusPropType,
+    indeterminate: uniqueOnStatePropType,
+    initialFocus: PropTypes.bool,
+    label: PropTypes.node,
+    name: PropTypes.string,
+    tabIndex: PropTypes.string,
+    valid: sharedPropTypes.statusPropType,
+    value: PropTypes.string,
+    warning: sharedPropTypes.statusPropType,
+    onBlur: PropTypes.func,
+    /** Called with signature `(object, event)` */
+    onChange: PropTypes.func,
+    onFocus: PropTypes.func,
+    onKeyDown: PropTypes.func,
+}
+
+export { Checkbox }

package/src/checkbox/checkbox.prod.stories.js

@@ -0,0 +1,182 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import React from 'react'
+import { Checkbox } from './index.js'
+
+const subtitle =
+    'A checkbox is a control that allows a user to toggle an option.'
+
+const description = `
+Checkboxes are used when an option can be toggled on or off. Toggling a checkbox on (true) is always considered a positive action and should reflect a positive/true/on state. Multiple checkboxes can be used in a list where a user can toggle multiple elements.
+
+Do not use checkboxes in a list of several options where only a single option can be toggled, use [radio buttons](../?path=/docs/forms-radio-radio--default) here instead.
+
+If there are many options that need to select from, consider using a [select](../?path=/docs/forms-single-select-single-select--with-options) instead.
+
+\`\`\`js
+import { Checkbox } from '@dhis2/ui'
+\`\`\`
+`
+
+window.onChange = (payload, event) => {
+    console.log('onClick payload', payload)
+    console.log('onClick event', event)
+}
+
+window.onFocus = (payload, event) => {
+    console.log('onFocus payload', payload)
+    console.log('onFocus event', event)
+}
+
+window.onBlur = (payload, event) => {
+    console.log('onBlur payload', payload)
+    console.log('onBlur event', event)
+}
+
+const onChange = (...args) => window.onChange(...args)
+const onFocus = (...args) => window.onFocus(...args)
+const onBlur = (...args) => window.onBlur(...args)
+
+const defaultArgs = { name: 'Ex', label: 'Checkbox', onChange, onFocus, onBlur }
+
+const uniqueOnStateArgType = {
+    table: {
+        type: {
+            summary: 'bool',
+            detail: "'checked' and 'indeterminate' are mutually exclusive props",
+        },
+    },
+    control: { type: 'boolean' },
+}
+
+export default {
+    title: 'Checkbox',
+    component: Checkbox,
+    parameters: {
+        componentSubtitle: subtitle,
+        docs: { description: { component: description } },
+    },
+    // Sets default args on all stories unless overridden
+    args: { ...defaultArgs },
+    argTypes: {
+        checked: { ...uniqueOnStateArgType },
+        indeterminate: { ...uniqueOnStateArgType },
+        valid: { ...sharedPropTypes.statusArgType },
+        warning: { ...sharedPropTypes.statusArgType },
+        error: { ...sharedPropTypes.statusArgType },
+    },
+}
+
+const Template = (args) => <Checkbox {...args} />
+
+const CheckedUncheckedTemplate = (args) => (
+    <>
+        <Checkbox {...args} />
+        <Checkbox checked {...args} />
+    </>
+)
+
+export const Default = Template.bind({})
+Default.args = { value: 'default' }
+
+export const FocusedUnchecked = (args) => (
+    <>
+        <Checkbox
+            initialFocus
+            value="default"
+            className="initially-focused"
+            {...args}
+        />
+        <Checkbox value="default2" className="initially-unfocused" {...args} />
+    </>
+)
+FocusedUnchecked.storyName = 'Focused unchecked'
+/**
+ * 'initialFocus' causes docs page to scroll away every time a control is
+ * changed, so it's disabled
+ */
+FocusedUnchecked.parameters = { docs: { disable: true } }
+
+export const FocusedChecked = (args) => (
+    <>
+        <Checkbox initialFocus checked value="default" {...args} />
+        <Checkbox checked value="default2" {...args} />
+    </>
+)
+FocusedChecked.storyName = 'Focused checked'
+FocusedChecked.parameters = { docs: { disable: true } }
+
+export const Checked = Template.bind({})
+Checked.args = { checked: true, value: 'checked' }
+
+export const Indeterminate = Template.bind({})
+Indeterminate.args = { indeterminate: true, value: 'checked' }
+
+export const Disabled = CheckedUncheckedTemplate.bind({})
+Disabled.args = { disabled: true, value: 'disabled' }
+
+export const Valid = CheckedUncheckedTemplate.bind({})
+Valid.args = { valid: true, value: 'valid' }
+
+export const Warning = CheckedUncheckedTemplate.bind({})
+Warning.args = { warning: true, value: 'warning' }
+
+export const Error = CheckedUncheckedTemplate.bind({})
+Error.args = { error: true, value: 'error' }
+
+export const ImageLabel = Template.bind({})
+ImageLabel.args = {
+    label: <img src="https://picsum.photos/id/82/200/100" />,
+    value: 'with-help',
+}
+
+export const DefaultDense = Template.bind({})
+DefaultDense.args = { dense: true, value: 'default' }
+DefaultDense.storyName = 'Default - Dense'
+
+export const FocusedUncheckedDense = Template.bind({})
+FocusedUncheckedDense.args = {
+    dense: true,
+    initialFocus: true,
+    value: 'default',
+}
+FocusedUncheckedDense.storyName = 'Focused unchecked - Dense'
+FocusedUncheckedDense.parameters = { docs: { disable: true } }
+
+export const FocusedCheckedDense = Template.bind({})
+FocusedCheckedDense.args = { ...FocusedUncheckedDense.args, checked: true }
+FocusedCheckedDense.storyName = 'Focused checked - Dense'
+FocusedCheckedDense.parameters = { docs: { disable: true } }
+
+export const CheckedDense = Template.bind({})
+CheckedDense.args = { dense: true, checked: true, value: 'checked' }
+CheckedDense.storyName = 'Checked - Dense'
+
+export const IndeterminateDense = Template.bind({})
+IndeterminateDense.args = { dense: true, indeterminate: true, value: 'checked' }
+IndeterminateDense.storyName = 'Indeterminate - Dense'
+
+export const DisabledDense = CheckedUncheckedTemplate.bind({})
+DisabledDense.args = { ...Disabled.args, dense: true }
+DisabledDense.storyName = 'Disabled - Dense'
+
+export const ValidDense = CheckedUncheckedTemplate.bind({})
+ValidDense.args = { ...Valid.args, dense: true }
+ValidDense.storyName = 'Valid - Dense'
+
+export const WarningDense = CheckedUncheckedTemplate.bind({})
+WarningDense.args = { ...Warning.args, dense: true }
+WarningDense.storyName = 'Warning - Dense'
+
+export const ErrorDense = CheckedUncheckedTemplate.bind({})
+ErrorDense.args = { ...Error.args, dense: true }
+ErrorDense.storyName = 'Error - Dense'
+
+export const ImageLabelDense = Template.bind({})
+ImageLabelDense.args = { ...ImageLabel.args, dense: true }
+ImageLabelDense.storyName = 'Image label - Dense'
+
+export const RTL = (args) => (
+    <div dir="rtl">
+        <Checkbox {...args} />
+    </div>
+)

package/src/checkbox/features/accepts_initial_focus/index.js

@@ -0,0 +1,9 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Checkbox with initialFocus is rendered', () => {
+    cy.visitStory('Checkbox', 'With initial focus')
+})
+
+Then('the Checkbox is focused', () => {
+    cy.focused().parent('[data-test="dhis2-uicore-checkbox"]').should('exist')
+})

package/src/checkbox/features/accepts_initial_focus.feature

@@ -0,0 +1,5 @@
+Feature: Focusing the Checkbox on mount
+
+    Scenario: The Checkbox renders with focus
+        Given a Checkbox with initialFocus is rendered
+        Then the Checkbox is focused

package/src/checkbox/features/accepts_label/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Checkbox with a label is rendered', () => {
+    cy.visitStory('Checkbox', 'With label')
+})
+
+Then('the label is shown', () => {
+    cy.get('[data-test="dhis2-uicore-checkbox"]')
+        .contains('The label')
+        .should('be.visible')
+})

package/src/checkbox/features/accepts_label.feature

@@ -0,0 +1,5 @@
+Feature: The Checkbox shows a label
+
+    Scenario: The Checkbox has a label
+        Given a Checkbox with a label is rendered
+        Then the label is shown

package/src/checkbox/features/can_be_blurred/index.js

@@ -0,0 +1,19 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Checkbox with initialFocus and onBlur handler is rendered', () => {
+    cy.visitStory('Checkbox', 'With initial focus and on blur')
+})
+
+When('the Checkbox is blurred', () => {
+    cy.get('[data-test="dhis2-uicore-checkbox"] input').blur()
+})
+
+Then('the onBlur handler is called', () => {
+    cy.window().should((win) => {
+        expect(win.onBlur).to.be.calledWith({
+            value: 'default',
+            name: 'Ex',
+            checked: true,
+        })
+    })
+})

package/src/checkbox/features/can_be_blurred.feature

@@ -0,0 +1,6 @@
+Feature: The Checkbox has an onBlur api
+
+    Scenario: The user blurs the Checkbox
+        Given a Checkbox with initialFocus and onBlur handler is rendered
+        When the Checkbox is blurred
+        Then the onBlur handler is called

package/src/checkbox/features/can_be_changed/index.js

@@ -0,0 +1,19 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Checkbox with onChange handler is rendered', () => {
+    cy.visitStory('Checkbox', 'With on change')
+})
+
+When('the Checkbox is clicked', () => {
+    cy.get('[data-test="dhis2-uicore-checkbox"]').click()
+})
+
+Then('the onChange handler is called', () => {
+    cy.window().should((win) => {
+        expect(win.onChange).to.be.calledWith({
+            value: 'default',
+            name: 'Ex',
+            checked: true,
+        })
+    })
+})

package/src/checkbox/features/can_be_changed.feature

@@ -0,0 +1,6 @@
+Feature: The Checkbox has an onChange api
+
+    Scenario: The user clicks the Checkbox
+        Given a Checkbox with onChange handler is rendered
+        When the Checkbox is clicked
+        Then the onChange handler is called

package/src/checkbox/features/can_be_disabled/index.js

@@ -0,0 +1,15 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a disabled Checkbox with onClick handler is rendered', () => {
+    cy.visitStory('Checkbox', 'Disabled with on click')
+})
+
+When('the Checkbox is clicked', () => {
+    cy.get('[data-test="dhis2-uicore-checkbox"] input').click({ force: true })
+})
+
+Then('the onClick handler is not called', () => {
+    cy.window().should((win) => {
+        expect(win.onClick).not.to.be.called
+    })
+})

package/src/checkbox/features/can_be_disabled.feature

@@ -0,0 +1,6 @@
+Feature: The Checkbox can be disabled
+
+    Scenario: The user clicks a disabled Checkbox
+        Given a disabled Checkbox with onClick handler is rendered
+        When the Checkbox is clicked
+        Then the onClick handler is not called

package/src/checkbox/features/can_be_focused/index.js

@@ -0,0 +1,19 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Checkbox with onFocus handler is rendered', () => {
+    cy.visitStory('Checkbox', 'With on focus')
+})
+
+When('the Checkbox is focused', () => {
+    cy.get('[data-test="dhis2-uicore-checkbox"] input').focus()
+})
+
+Then('the onFocus handler is called', () => {
+    cy.window().should((win) => {
+        expect(win.onFocus).to.be.calledWith({
+            value: 'default',
+            name: 'Ex',
+            checked: true,
+        })
+    })
+})

package/src/checkbox/features/can_be_focused.feature

@@ -0,0 +1,6 @@
+Feature: The Checkbox has an onFocus api
+
+    Scenario: The user focuses the Checkbox
+        Given a Checkbox with onFocus handler is rendered
+        When the Checkbox is focused
+        Then the onFocus handler is called

package/src/checkbox/features/has_indeterminate_prop/index.js

@@ -0,0 +1,19 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('the checkbox is marked as indeterminate', () => {
+    cy.visitStory('Checkbox', 'Indeterminate prop')
+})
+
+Given('the checkbox is not marked as indeterminate', () => {
+    cy.visitStory('Checkbox', 'No indeterminate prop')
+})
+
+Then("its input-element's indeterminate prop is {word}", (bool) => {
+    cy.get('input').should(($input) => {
+        if (bool === 'true') {
+            expect($input[0].indeterminate).to.be.true
+        } else {
+            expect($input[0].indeterminate).to.be.false
+        }
+    })
+})

package/src/checkbox/features/has_indeterminate_prop.feature

@@ -0,0 +1,9 @@
+Feature: The input component has an indeterminate prop
+
+    Scenario: The checkbox has the indeterminate prop
+        Given the checkbox is marked as indeterminate
+        Then its input-element's indeterminate prop is true
+
+    Scenario: The checkbox does not have the indeterminate prop
+        Given the checkbox is not marked as indeterminate
+        Then its input-element's indeterminate prop is false

package/src/checkbox/index.js

@@ -0,0 +1 @@
+export { Checkbox } from './checkbox.js'

package/src/checkbox-field/__tests__/checkbox-field.test.js

@@ -0,0 +1,32 @@
+import { render, fireEvent, screen } from '@testing-library/react'
+import React from 'react'
+import { CheckboxField } from '../checkbox-field.js'
+
+describe('<CheckboxField />', () => {
+    it('should call the onKeyDown callback when provided', () => {
+        const onKeyDown = jest.fn()
+
+        render(
+            <CheckboxField
+                label="Label"
+                name="foo"
+                value="bar"
+                checked={false}
+                onKeyDown={onKeyDown}
+            />
+        )
+
+        fireEvent.keyDown(screen.getByRole('checkbox'), {
+            key: 'Enter',
+            code: 'Enter',
+            charCode: 13,
+        })
+
+        expect(onKeyDown).toHaveBeenCalledWith(
+            { name: 'foo', value: 'bar', checked: true },
+            expect.objectContaining({})
+        )
+
+        expect(onKeyDown).toHaveBeenCalledTimes(1)
+    })
+})

package/src/checkbox-field/checkbox-field.e2e.stories.js

@@ -0,0 +1,26 @@
+import React from 'react'
+import { CheckboxField } from './index.js'
+
+export default { title: 'CheckboxField' }
+export const WithLabelAndRequired = () => (
+    <CheckboxField name="Ex" label="CheckboxField" required value="checked" />
+)
+export const WithHelpText = () => (
+    <CheckboxField
+        name="Ex"
+        label="CheckboxField"
+        value="checked"
+        helpText="Help text"
+    />
+)
+export const WithLabel = () => (
+    <CheckboxField name="Ex" label="The label" value="checked" />
+)
+export const WithValidationText = () => (
+    <CheckboxField
+        name="Ex"
+        label="The label"
+        value="checked"
+        validationText="Validation text"
+    />
+)

package/src/checkbox-field/checkbox-field.js

@@ -0,0 +1,116 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import { Field } from '@dhis2-ui/field'
+import { Required } from '@dhis2-ui/required'
+import PropTypes from 'prop-types'
+import React from 'react'
+import { Checkbox } from '../checkbox/index.js'
+
+const AddRequired = ({ label, required, dataTest }) => (
+    <React.Fragment>
+        {label}
+        {required && <Required dataTest={`${dataTest}-required`} />}
+    </React.Fragment>
+)
+AddRequired.propTypes = {
+    dataTest: PropTypes.string,
+    label: PropTypes.node,
+    required: PropTypes.bool,
+}
+
+const CheckboxField = ({
+    value,
+    label,
+    name,
+    className,
+    tabIndex,
+    onChange,
+    onFocus,
+    onKeyDown,
+    onBlur,
+    checked,
+    disabled,
+    valid,
+    warning,
+    error,
+    dense,
+    initialFocus,
+    required,
+    helpText,
+    validationText,
+    dataTest = 'dhis2-uiwidgets-checkboxfield',
+}) => (
+    <Field
+        className={className}
+        dataTest={dataTest}
+        helpText={helpText}
+        validationText={validationText}
+        error={error}
+        warning={warning}
+        valid={valid}
+        disabled={disabled}
+    >
+        <Checkbox
+            value={value}
+            label={
+                <AddRequired
+                    label={label}
+                    required={required}
+                    dataTest={dataTest}
+                />
+            }
+            name={name}
+            tabIndex={tabIndex}
+            onChange={onChange}
+            onFocus={onFocus}
+            onKeyDown={onKeyDown}
+            onBlur={onBlur}
+            checked={checked}
+            disabled={disabled}
+            valid={valid}
+            warning={warning}
+            error={error}
+            dense={dense}
+            initialFocus={initialFocus}
+        />
+    </Field>
+)
+
+CheckboxField.propTypes = {
+    checked: PropTypes.bool,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** Smaller dimensions for information-dense layouts */
+    dense: PropTypes.bool,
+    /** Disables the checkbox */
+    disabled: PropTypes.bool,
+    /** Applies 'error' styling to checkbox and validation text for feedback. Mutually exclusive with `warning` and `valid` props */
+    error: sharedPropTypes.statusPropType,
+    /** Useful instructions for the user */
+    helpText: PropTypes.string,
+    initialFocus: PropTypes.bool,
+    /** Labels the checkbox */
+    label: PropTypes.node,
+    /** Name associate with the checkbox. Passed in object as argument to event handlers */
+    name: PropTypes.string,
+    /** Adds an asterisk to indicate this field is required */
+    required: PropTypes.bool,
+    tabIndex: PropTypes.string,
+    /** Applies 'valid' styling to checkbox and validation text for feedback. Mutually exclusive with `warning` and `error` props */
+    valid: sharedPropTypes.statusPropType,
+    /** Adds text below the checkbox to provide validation feedback. Acquires styles from `valid`, `warning` and `error` statuses */
+    validationText: PropTypes.string,
+    /** Value associated with the checkbox. Passed in object as argument to event handlers */
+    value: PropTypes.string,
+    /** Applies 'warning' styling to checkbox and validation text for feedback. Mutually exclusive with `valid` and `error` props */
+    warning: sharedPropTypes.statusPropType,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onBlur: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onChange: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onFocus: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onKeyDown: PropTypes.func,
+}
+
+export { CheckboxField }

package/src/checkbox-field/checkbox-field.prod.stories.js

@@ -0,0 +1,149 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import React from 'react'
+import { CheckboxField } from './index.js'
+
+const description = `
+A \`CheckboxField\` is a Checkbox component wrapped with extra form utilities, including the ability to add a label, help text, and validation text.  Validation styles like 'error' apply to all of these subcomponents.
+
+See the basic Checkbox for usage and design system guidelines.
+
+\`\`\`js
+import { CheckboxField } from '@dhis2/ui'
+\`\`\`
+`
+
+const logger = ({ name, value, checked }) =>
+    console.log(`name: ${name}, value: ${value}, checked: ${checked}`)
+
+export default {
+    title: 'Checkbox Field',
+    component: CheckboxField,
+    parameters: { docs: { description: { component: description } } },
+    // Default args for stories
+    args: {
+        name: 'checkboxName',
+        label: 'Checkbox Field',
+        value: 'defaultValue',
+        onChange: logger,
+    },
+    argTypes: {
+        valid: { ...sharedPropTypes.statusArgType },
+        warning: { ...sharedPropTypes.statusArgType },
+        error: { ...sharedPropTypes.statusArgType },
+    },
+}
+
+const Template = (args) => <CheckboxField {...args} />
+
+const CheckedUncheckedTemplate = (args) => (
+    <>
+        <CheckboxField {...args} />
+        <CheckboxField {...args} checked />
+    </>
+)
+
+export const Default = Template.bind({})
+
+export const FocusedUnchecked = Template.bind({})
+FocusedUnchecked.args = { initialFocus: true }
+// Disable stories on docs page that grab focus
+FocusedUnchecked.parameters = { docs: { disable: true } }
+
+export const FocusedChecked = Template.bind({})
+FocusedChecked.args = { ...FocusedUnchecked.args, checked: true }
+FocusedChecked.parameters = { docs: { disable: true } }
+
+export const Checked = Template.bind({})
+Checked.args = { checked: true, value: 'checkedValue' }
+
+export const Required = Template.bind({})
+Required.args = { required: true }
+
+export const Disabled = CheckedUncheckedTemplate.bind({})
+Disabled.args = { disabled: true }
+
+export const HelpText = (args) => (
+    <>
+        <CheckboxField {...args} />
+        <CheckboxField
+            {...args}
+            error
+            validationText="Validation text (error state)"
+        />
+    </>
+)
+HelpText.args = { helpText: 'Help text' }
+
+export const Valid = CheckedUncheckedTemplate.bind({})
+Valid.args = {
+    valid: true,
+    validationText: 'I am validation text',
+    value: 'validValue',
+}
+
+export const Warning = CheckedUncheckedTemplate.bind({})
+Warning.args = {
+    warning: true,
+    value: 'warningValue',
+    validationText: 'I am validation text',
+}
+
+export const Error = CheckedUncheckedTemplate.bind({})
+Error.args = {
+    error: true,
+    value: 'errorValue',
+    validationText: 'I am validation text',
+}
+
+export const ImageLabel = Template.bind({})
+ImageLabel.args = { label: <img src="https://picsum.photos/id/82/200/100" /> }
+
+export const DefaultDense = Template.bind({})
+DefaultDense.storyName = 'Default - Dense'
+DefaultDense.args = { dense: true }
+
+export const FocusedUncheckedDense = Template.bind({})
+FocusedUncheckedDense.args = { ...DefaultDense.args, ...FocusedUnchecked.args }
+FocusedUncheckedDense.parameters = { docs: { disable: true } }
+FocusedUncheckedDense.storyName = 'Focused unchecked - Dense'
+
+export const FocusedCheckedDense = Template.bind({})
+FocusedCheckedDense.args = { ...DefaultDense.args, ...FocusedChecked.args }
+FocusedCheckedDense.parameters = { docs: { disable: true } }
+FocusedCheckedDense.storyName = 'Focused checked - Dense'
+
+export const CheckedDense = Template.bind({})
+CheckedDense.args = { ...DefaultDense.args, ...Checked.args }
+CheckedDense.storyName = 'Checked - Dense'
+
+export const RequiredDense = Template.bind({})
+RequiredDense.args = { ...DefaultDense.args, ...Required.args }
+RequiredDense.storyName = 'Required - Dense'
+
+export const DisabledDense = CheckedUncheckedTemplate.bind({})
+DisabledDense.args = { ...DefaultDense.args, ...Disabled.args }
+DisabledDense.storyName = 'Disabled - Dense'
+
+export const ValidDense = CheckedUncheckedTemplate.bind({})
+ValidDense.args = { ...DefaultDense.args, ...Valid.args }
+ValidDense.storyName = 'Valid - Dense'
+
+export const WarningDense = CheckedUncheckedTemplate.bind({})
+WarningDense.args = { ...DefaultDense.args, ...Warning.args }
+WarningDense.storyName = 'Warning - Dense'
+
+export const ErrorDense = CheckedUncheckedTemplate.bind({})
+ErrorDense.args = { ...DefaultDense.args, ...Error.args }
+ErrorDense.storyName = 'Error - Dense'
+
+export const ImageLabelDense = Template.bind({})
+ImageLabelDense.args = { ...DefaultDense.args, ...ImageLabel.args }
+ImageLabelDense.storyName = 'Image label - Dense'
+
+export const RTL = (args) => (
+    <div dir="rtl">
+        <>
+            <CheckboxField {...args} />
+        </>
+    </div>
+)

package/src/checkbox-field/features/accepts_help_text/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a CheckboxField with help text is rendered', () => {
+    cy.visitStory('CheckboxField', 'With help text')
+})
+
+Then('the help text is visible', () => {
+    cy.get('[data-test="dhis2-uiwidgets-checkboxfield-help"]')
+        .contains('Help text')
+        .should('be.visible')
+})

package/src/checkbox-field/features/accepts_help_text.feature

@@ -0,0 +1,5 @@
+Feature: Help text for the CheckboxField
+
+    Scenario: Rendering a CheckboxField with help text
+        Given a CheckboxField with help text is rendered
+        Then the help text is visible

package/src/checkbox-field/features/accepts_label/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a CheckboxField with a label is rendered', () => {
+    cy.visitStory('CheckboxField', 'With label')
+})
+
+Then('the label is visible', () => {
+    cy.get('[data-test="dhis2-uiwidgets-checkboxfield"]')
+        .contains('The label')
+        .should('be.visible')
+})

package/src/checkbox-field/features/accepts_label.feature

@@ -0,0 +1,5 @@
+Feature: Label for the CheckboxField
+
+    Scenario: Rendering a CheckboxField with a label
+        Given a CheckboxField with a label is rendered
+        Then the label is visible

package/src/checkbox-field/features/accepts_validation_text/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a CheckboxField with validation text is rendered', () => {
+    cy.visitStory('CheckboxField', 'With validation text')
+})
+
+Then('the validation text is visible', () => {
+    cy.get('[data-test="dhis2-uiwidgets-checkboxfield-validation"]')
+        .contains('Validation text')
+        .should('be.visible')
+})

package/src/checkbox-field/features/accepts_validation_text.feature

@@ -0,0 +1,5 @@
+Feature: Validation text for the CheckboxField
+
+    Scenario: Rendering a CheckboxField with validation text
+        Given a CheckboxField with validation text is rendered
+        Then the validation text is visible

package/src/checkbox-field/features/can_be_required/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a CheckboxField with label and a required flag is rendered', () => {
+    cy.visitStory('CheckboxField', 'With label and required')
+})
+
+Then('the required indicator is visible', () => {
+    cy.get('[data-test="dhis2-uiwidgets-checkboxfield-required"]').should(
+        'be.visible'
+    )
+})

package/src/checkbox-field/features/can_be_required.feature

@@ -0,0 +1,5 @@
+Feature: Required status for the CheckboxField
+
+    Scenario: Rendering a CheckboxField that is required
+        Given a CheckboxField with label and a required flag is rendered
+        Then the required indicator is visible

package/src/checkbox-field/index.js

@@ -0,0 +1 @@
+export { CheckboxField } from './checkbox-field.js'

package/src/index.js

@@ -0,0 +1,2 @@
+export { Checkbox } from './checkbox/index.js'
+export { CheckboxField } from './checkbox-field/index.js'