---
applyTo: "**/*.tsx,**/*.jsx"
---

# @cfx-dev/ui-components — Layout Components

All layout components are imported from `@cfx-dev/ui-components`.

## Responsive Props Pattern

Layout components accept responsive values for sizing/spacing props. Three formats:

```tsx
// 1. Single value (number = quant multiplier)
<Flex gap={4} />           // gap = ui.q(4) = 1rem

// 2. Spacer/spacing token (string)
<Flex gap="xlarge" />      // gap = var(--spacer-xlarge)

// 3. Responsive object (breakpoint → value)
<Flex gap={{ initial: 2, bp768: 4, bp1280: 6 }} />
```

Breakpoint names: `initial`, `bp320`, `bp393`, `bp500`, `bp768`, `bp1024`, `bp1280`, `bp1440`, `bp1920`, `bp2560`.

## Margin & Padding (MPProps)

`Box` and `Flex` extend `MPProps` — shorthand margin/padding props:

```tsx
<Box mt={2} mb={4} px="large" />
<Flex py={{ initial: 2, bp768: 4 }} mx="xlarge" />
```

Available: `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`.
Values accept quant numbers, spacer tokens (`xxsmall`..`xxxxxlarge`), or spacing tokens (`sp100`..`sp2400`).

## Box

Generic container with responsive `width`, `height`, `display`, `flex`, and margin/padding props:

```tsx
import { Box } from '@cfx-dev/ui-components';

<Box
  fullWidth
  noOverflow
  display={{ initial: 'none', bp768: 'block' }}
  p={2}
  as="section"
>
  {children}
</Box>
```

Key props: `noOverflow`, `noShrink`, `grow`, `fullWidth`, `fullHeight`, `fitContentWidth`, `as` (element type), `display`, `width`, `height`, `flex`, plus all `MPProps`.

## Flex

Flexbox container extending `Box`:

```tsx
import { Flex, FlexRestricter } from '@cfx-dev/ui-components';

// Horizontal with gap
<Flex gap={2} centered>
  <Button text="A" />
  <Button text="B" />
</Flex>

// Vertical stack
<Flex vertical gap="large" stretch>
  <Text>Line 1</Text>
  <Text>Line 2</Text>
</Flex>

// Responsive layout
<Flex
  direction={{ initial: 'column', bp768: 'row' }}
  gap={{ initial: 2, bp1024: 4 }}
  wrap={{ initial: true, bp1280: false }}
>
  {children}
</Flex>
```

Key props: `vertical`, `centered` (`true` | `'axis'` | `'cross-axis'` | `'baseline-axis'` | `'baseline-cross-axis'`), `stretch`, `spaceBetween`, `alignToEnd`, `alignToEndAxis`, `reverseOrder`, `gap`, `direction`, `alignItems`, `justifyContent`, `wrap`, plus all `Box` props.

`FlexRestricter` — prevents flex children from overflowing (sets `min-width: 0`):

```tsx
<Flex>
  <FlexRestricter>{longContent}</FlexRestricter>
</Flex>
```

## Spacer

Adds fixed spacing between elements:

```tsx
import { Spacer } from '@cfx-dev/ui-components';

<Spacer size="large" />             {/* horizontal spacer */}
<Spacer size="normal" vertical />   {/* vertical spacer */}
```

Sizes: `none`, `hairthin`, `thin`, `xxsmall`, `xsmall`, `small`, `normal` (default), `medium`, `large`, `xlarge`, `safezone`.

## Separator

Visual divider line with optional text content:

```tsx
import { Separator } from '@cfx-dev/ui-components';

<Separator />                           {/* full-width line */}
<Separator thin />                      {/* thinner line */}
<Separator content="OR" />              {/* line with text */}
<Separator vertical />                  {/* vertical divider */}
<Separator my={4} />                    {/* with margin (MPProps) */}
```

## Scrollable

Scrollable container with custom-styled scrollbars:

```tsx
import { Scrollable, VirtualScrollable } from '@cfx-dev/ui-components';

<Scrollable>{longContent}</Scrollable>

// Virtualized list (react-window powered) for large datasets:
<VirtualScrollable
  itemCount={1000}
  itemSize={40}
  height={400}
>
  {({ index, style }) => <div style={style}>Row {index}</div>}
</VirtualScrollable>
```

## Layout Helpers

```tsx
import { Center, Pad, Page } from '@cfx-dev/ui-components';

<Center>{children}</Center>           {/* centered content */}
<Pad size="large">{children}</Pad>    {/* padded container */}
<Page>{children}</Page>               {/* page-level wrapper */}
```