@fvc/box

@fvc/box provides FE-VIS flexbox layout primitives on top of Ant Design Grid. It exposes a Box component for flex containers and compound subcomponents Box.Row and Box.Column for grid-based layouts, keeping the Ant Design Row/Col API familiar while adding direction, alignment, gap, and block layout controls as props.

Installation

bun add @fvc/box

Peer Dependencies

bun add react antd

Import

import { Box } from '@fvc/box';

Quick Start

import { Box } from '@fvc/box';

export function ActionBar() {
  return (
    <Box direction="row" justify="space-between" align="center">
      <span>Title</span>
      <button>Save</button>
    </Box>
  );
}

Components

| Component | Use case | | --- | --- | | Box | Flex container with direction, alignment, gap, and wrap controls. | | Box.Row | Ant Design Row wrapper with testId support. | | Box.Column | Ant Design Col wrapper with col shorthand and testId support. |

Common Usage

Flex Row

<Box direction="row" align="center" justify="space-between">
  <Label>Status</Label>
  <Value>Active</Value>
</Box>

Flex Column

<Box direction="column" rowGap={1}>
  <Field label="Name" />
  <Field label="Email" />
  <Field label="Phone" />
</Box>

No Wrap

<Box direction="row" wrap={false}>
  <Tag>Tag 1</Tag>
  <Tag>Tag 2</Tag>
</Box>

Full Width

<Box direction="row" block>
  <SearchInput />
  <Button type="primary">Search</Button>
</Box>

Inline Flex

<Box display="inline-flex" align="center" direction="row">
  <Icon />
  <span>Label</span>
</Box>

Row and Column Grid

<Box.Row gutter={16}>
  <Box.Column col={12}>
    <Input name="firstName" label="First name" />
  </Box.Column>
  <Box.Column col={12}>
    <Input name="lastName" label="Last name" />
  </Box.Column>
</Box.Row>

Props

Box

| Prop | Type | Description | | --- | --- | --- | | display | 'flex' \| 'inline-flex' | Display mode. Defaults to 'flex'. | | direction | 'row' \| 'column' \| 'row-reverse' \| 'column-reverse' | Flex direction. | | align | 'flex-start' \| 'center' \| 'flex-end' | Cross-axis alignment. | | justify | 'flex-start' \| 'center' \| 'flex-end' \| 'space-between' \| 'space-around' | Main-axis alignment. | | wrap | boolean | Enable flex wrapping. Defaults to true. | | block | boolean | Set width to 100%. | | rowGap | number | Gap between rows in rem units. | | height | string | Sets minHeight. | | className | string | Additional CSS class names. | | style | CSSProperties | Inline styles. | | testId | string | Maps to data-testid. | | children | ReactNode | Content. |

Box.Column

| Prop | Type | Description | | --- | --- | --- | | col | number | Shorthand for span. | | testId | string | Maps to data-testid. | | All ColProps | — | All Ant Design Col props (span, offset, xs, sm, md, lg, xl, xxl, etc.). |

Box.Row

| Prop | Type | Description | | --- | --- | --- | | testId | string | Maps to data-testid. | | All RowProps | — | All Ant Design Row props (gutter, align, justify, wrap, etc.). |

Consumer Example

import { Box } from '@fvc/box';

export function FilterBar({ onSearch, onReset }) {
  return (
    <Box direction="column" rowGap={1} block>
      <Box.Row gutter={16}>
        <Box.Column col={8}>
          <Input name="name" label="Name" />
        </Box.Column>
        <Box.Column col={8}>
          <Input name="status" label="Status" />
        </Box.Column>
        <Box.Column col={8}>
          <Input name="date" label="Date" />
        </Box.Column>
      </Box.Row>

      <Box direction="row" justify="flex-end">
        <Button type="secondary" onClick={onReset}>Reset</Button>
        <Button type="primary" onClick={onSearch}>Search</Button>
      </Box>
    </Box>
  );
}

Testing

<Box direction="row" testId="action-bar">
  <Button>Save</Button>
</Box>

screen.getByTestId('action-bar');

Customisation

@fvc/box 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 {
  --box-bg-color: #f9fafb;
  --box-border-width: 1px;
  --box-border-color: #e5e7eb;
  --box-border-radius: 8px;
  --box-padding: 16px;
}

Available variables

| Variable | Default | Controls | | --- | --- | --- | | --box-bg-color | transparent | Background color of the Box container | | --box-border-width | 0 | Border thickness of the Box container | | --box-border-color | transparent | Border color of the Box container | | --box-border-radius | 0 | Corner radius of the Box container | | --box-padding | 0 | Inner padding of the Box container | | --box-col-min-height | 1px | Minimum height of the fvc-box-col sub-element |

Development

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