@fvc/checkbox

@fvc/checkbox provides FE-VIS styled checkbox primitives on top of Ant Design Checkbox. It keeps the Ant Design Checkbox API familiar while adding size variants, visibility control, full-width layout, white-space wrapping, and a grouped layout mode.

Installation

bun add @fvc/checkbox

Peer Dependencies

bun add react antd

Import

import { Checkbox } from '@fvc/checkbox';

Quick Start

import { Checkbox } from '@fvc/checkbox';

export function AgreeField() {
  return (
    <Checkbox onChange={(e) => setAgreed(e.target.checked)}>
      I agree to the terms and conditions
    </Checkbox>
  );
}

Components

| Component | Use case | | --- | --- | | Checkbox | Single checkbox. | | Checkbox.Group | Group of checkboxes with optional block layout. |

Common Usage

Controlled

<Checkbox
  checked={agreed}
  onChange={(e) => setAgreed(e.target.checked)}
>
  I agree to the terms
</Checkbox>

Sizes

<Checkbox size="medium">Medium (default)</Checkbox>
<Checkbox size="small">Small</Checkbox>

Indeterminate

<Checkbox indeterminate={someChecked} checked={allChecked} onChange={handleAll}>
  Select all
</Checkbox>

Disabled

<Checkbox disabled>Unavailable option</Checkbox>

Full Width

<Checkbox fullWidth>Full-width checkbox label</Checkbox>

Wrapping Long Labels

<Checkbox whiteSpaceWrapped>
  This is a very long checkbox label that should wrap onto the next line without being truncated.
</Checkbox>

Hidden

<Checkbox visible={false}>Hidden but rendered</Checkbox>

Group

<Checkbox.Group
  options={[
    { label: 'Option A', value: 'a' },
    { label: 'Option B', value: 'b' },
    { label: 'Option C', value: 'c' },
  ]}
  value={selected}
  onChange={setSelected}
/>

Group Block Layout

<Checkbox.Group
  block
  options={[
    { label: 'Read', value: 'read' },
    { label: 'Write', value: 'write' },
    { label: 'Delete', value: 'delete' },
  ]}
  value={permissions}
  onChange={setPermissions}
/>

Props

Checkbox

| Prop | Type | Description | | --- | --- | --- | | size | 'medium' \| 'small' | Checkbox size. Defaults to 'medium'. | | visible | boolean | Controls visibility without removing from DOM. Defaults to true. | | fullWidth | boolean | Stretches the checkbox to full container width. | | whiteSpaceWrapped | boolean | Allows the label text to wrap onto multiple lines. | | testId | string | Maps to data-testid. | | All CheckboxProps | — | All Ant Design Checkbox props (checked, defaultChecked, indeterminate, disabled, onChange, etc.). |

Checkbox.Group

| Prop | Type | Description | | --- | --- | --- | | block | boolean | Displays each checkbox as a full-width block item. | | All CheckboxGroupProps | — | All Ant Design CheckboxGroup props (options, value, defaultValue, disabled, onChange, etc.). |

Consumer Example

import { Checkbox } from '@fvc/checkbox';

export function PermissionsField({ value, onChange }) {
  return (
    <Checkbox.Group
      block
      options={[
        { label: 'View records', value: 'view' },
        { label: 'Create records', value: 'create' },
        { label: 'Edit records', value: 'edit' },
        { label: 'Delete records', value: 'delete' },
      ]}
      value={value}
      onChange={onChange}
    />
  );
}

Testing

<Checkbox testId="agree-checkbox">I agree</Checkbox>

screen.getByTestId('agree-checkbox');

Customisation

@fvc/checkbox exposes its visual tokens as CSS custom properties declared in src/styles/variables.scss. Override any of these in your own stylesheet — no fork, no file in the component, no re-bundle required.

/* consumer's own app stylesheet */
:root {
  --checkbox-border-color: #6941c6;
  --checkbox-checked-bg-color: #6941c6;
  --checkbox-checked-mark-color: #ffffff;
}

Available variables

| Variable | Default | Controls | | --- | --- | --- | | --checkbox-size | 18px | Width and height of the medium checkbox box | | --checkbox-small-size | 14px | Width and height of the small checkbox box | | --checkbox-border-width | 2px | Border thickness of the checkbox box | | --checkbox-border-radius | 2px | Corner radius of the checkbox box | | --checkbox-border-color | var(--blue-500) | Default border color of the unchecked checkbox | | --checkbox-hover-border-color | var(--blue-500) | Border color when hovering over an unchecked checkbox | | --checkbox-checked-bg-color | var(--blue-500) | Background fill of the checked checkbox | | --checkbox-checked-mark-color | var(--neutral-0) | Color of the checkmark tick | | --checkbox-indeterminate-border-color | var(--blue-500) | Border color of the indeterminate checkbox | | --checkbox-indeterminate-bg-color | var(--neutral-0) | Background of the indeterminate checkbox inner area | | --checkbox-indeterminate-mark-color | var(--blue-500) | Color of the indeterminate dash | | --checkbox-disabled-border-color | var(--blue-300) | Border color of a disabled checkbox | | --checkbox-disabled-bg-color | var(--neutral-0) | Background of a disabled unchecked checkbox | | --checkbox-disabled-checked-bg-color | var(--blue-300) | Background fill of a disabled checked checkbox |

Development

bun run lint
bun run type-check
bun run test
bun run build