Skip to content

Flex

General-purpose flex container — direction, align, justify, wrap, gap, plus grow/shrink/basis as props. The escape hatch when Stack/Inline don't quite fit.

stable
since v0.1.0
3.71 kB
primitive
layout
flex

Preview

tsx

import { Box, Flex } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Flex
      direction="row"
      gap="3"
      justify="between"
      align="center"
      padding="4"
      background="bg.subtle"
      borderRadius="md"
    >
      <Box padding="3" background="bg.surface" borderRadius="sm">
        Left
      </Box>
      <Box padding="3" background="bg.surface" borderRadius="sm">
        Middle
      </Box>
      <Box padding="3" background="bg.surface" borderRadius="sm">
        Right
      </Box>
    </Flex>
  );
}

Direction

direction accepts row (default), column, and the matching *-reverse variants. All four accept a responsive map — a common pattern is direction={{ base: 'column', md: 'row' }} for “stack on mobile, side-by-side on desktop”.

Preview

tsx

import { Box, Flex } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Flex
      direction={{ base: 'column', md: 'row' }}
      gap="3"
      padding="4"
      background="bg.subtle"
      borderRadius="md"
    >
      <Box padding="3" background="bg.surface" borderRadius="sm" flex="1">
        Stacks on narrow viewports
      </Box>
      <Box padding="3" background="bg.surface" borderRadius="sm" flex="1">
        Sits side-by-side from `md` up
      </Box>
    </Flex>
  );
}

Grow, shrink, basis

The grow, shrink, and basis props are flex-item hints. They apply to the child Boxes (Box, Stack, Inline, Flex, Grid all forward these), letting a child claim or yield space inside a Flex parent without writing custom CSS.

Preview

tsx

import { Box, Flex } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Flex gap="3" padding="4" background="bg.subtle" borderRadius="md">
      <Box padding="3" background="bg.surface" borderRadius="sm">
        Fixed
      </Box>
      <Box padding="3" background="bg.surface" borderRadius="sm" flex="1">
        Grows to fill remaining space
      </Box>
      <Box padding="3" background="bg.surface" borderRadius="sm">
        Fixed
      </Box>
    </Flex>
  );
}

API

PropTypeDefaultDescription

className

string

—

Additional class names appended after Cynosure's base classes.

style

CSSProperties

—

Inline style overrides merged last.

children

ReactNode

—

Flex children.

direction

Responsive<FlexDirection>

—

Main-axis direction — `row`, `column`, or their reversed variants.

wrap

Responsive<FlexWrap>

—

`flex-wrap` setting. Use `wrap-reverse` to wrap in the opposite direction.

grow

Responsive<number | `${number}`>

—

`flex-grow` applied to *this* container (not its children).

shrink

Responsive<number | `${number}`>

—

`flex-shrink` applied to *this* container (not its children).

basis

Responsive<`${number}px` | `${number}%` | MarginValue>

—

`flex-basis` applied to *this* container.

gap

Responsive<SpaceToken>

—

Uniform gap in both axes. Falls back to `rowGap`/`columnGap` when set.

rowGap

Responsive<SpaceToken>

—

Gap between wrapped rows. Overrides the row axis of `gap`.

columnGap

Responsive<SpaceToken>

—

Gap between adjacent items on the inline axis. Overrides `gap`'s columns.

align

Responsive<FlexAlign>

—

Cross-axis alignment — maps to `align-items`. Supports `baseline`.

justify

Responsive<FlexJustify>

—

Main-axis distribution — maps to `justify-content`.

padding

Responsive<SpaceToken>

—

Padding on all four sides. Token from the spacing scale.

paddingX

Responsive<SpaceToken>

—

Horizontal padding (left + right). Overrides `padding` on the X axis.

paddingY

Responsive<SpaceToken>

—

Vertical padding (top + bottom). Overrides `padding` on the Y axis.

paddingTop

Responsive<SpaceToken>

—

Padding on the top edge. Beats `padding` / `paddingY`.

paddingRight

Responsive<SpaceToken>

—

Padding on the right (inline-end in RTL) edge.

paddingBottom

Responsive<SpaceToken>

—

Padding on the bottom edge.

paddingLeft

Responsive<SpaceToken>

—

Padding on the left (inline-start in RTL) edge.

margin

Responsive<MarginValue>

—

Margin on all four sides. Accepts the spacing scale or `"auto"`.

marginX

Responsive<MarginValue>

—

Horizontal margin (left + right). Use `"auto"` to centre.

marginY

Responsive<MarginValue>

—

Vertical margin (top + bottom).

marginTop

Responsive<MarginValue>

—

Margin on the top edge.

marginRight

Responsive<MarginValue>

—

Margin on the right edge.

marginBottom

Responsive<MarginValue>

—

Margin on the bottom edge.

marginLeft

Responsive<MarginValue>

—

Margin on the left edge.

width

Responsive<SizeValue>

—

Element width. Accepts a `SpaceToken`, `LengthValue`, or named alias.

height

Responsive<SizeValue>

—

Element height. Accepts a `SpaceToken`, `LengthValue`, or named alias.

minWidth

Responsive<SizeValue>

—

Minimum width — useful for preventing flex children from collapsing.

maxWidth

Responsive<SizeValue>

—

Maximum width — `"prose"` caps to a comfortable reading measure.

minHeight

Responsive<SizeValue>

—

Minimum height.

maxHeight

Responsive<SizeValue>

—

Maximum height.

background

Responsive<ColorToken>

—

Background colour. Use a `ColorToken` like `"bg.surface"` for theme awareness.

color

Responsive<ColorToken>

—

Text colour. Inherits unless set.

borderColor

Responsive<ColorToken>

—

Border colour. Pair with `borderWidth` to make the border visible.

borderWidth

Responsive<BorderWidth>

—

Border thickness in scale steps.

borderStyle

Responsive<BorderStyle>

—

Border line style.

borderRadius

Responsive<RadiusToken>

—

Corner rounding token.

boxShadow

Responsive<ShadowToken>

—

Drop-shadow token from the elevation scale.

opacity

Responsive<number | `${number}`>

—

Opacity 0–1. Use sparingly — prefer surface tokens over translucency.

overflow

Responsive<Overflow>

—

How content that exceeds the box is handled.

overflowX

Responsive<Overflow>

—

Horizontal-axis overflow control. Overrides `overflow` for the X axis.

overflowY

Responsive<Overflow>

—

Vertical-axis overflow control.

display

Responsive<Display>

—

CSS `display` value. `"contents"` removes the element's box from layout.

position

Responsive<Position>

—

CSS `position`. Pair with `top`/`right`/`bottom`/`left` for placement.

top

Responsive<InsetValue>

—

Top inset (when positioned). Accepts a `SpaceToken`, `"auto"`, `"0"`, or `LengthValue`.

right

Responsive<InsetValue>

—

Right inset (when positioned).

bottom

Responsive<InsetValue>

—

Bottom inset (when positioned).

left

Responsive<InsetValue>

—

Left inset (when positioned).

zIndex

Responsive<ZIndexToken>

—

Stacking-context layer token (`"modal"`, `"tooltip"`, …).

gridColumn

Responsive<string>

—

Grid-column shorthand (e.g. `"1 / 3"`, `"span 2"`).

gridRow

Responsive<string>

—

Grid-row shorthand.

gridArea

Responsive<string>

—

Named grid area.

flex

Responsive<"1" | "none" | "auto" | "initial" | (string & {})>

—

Shorthand: `1 | auto | none | initial | <css>`. Resolves to `flex` on the child.

flexGrow

Responsive<number | `${number}`>

—

Grow factor inside a flex container.

flexShrink

Responsive<number | `${number}`>

—

Shrink factor inside a flex container.

flexBasis

Responsive<SizeValue | "content">

—

Initial main-axis size before grow/shrink.

alignSelf

Responsive<AlignSelf>

—

Override `align-items` for a single child.

justifySelf

Responsive<JustifySelf>

—

Override `justify-items` for a single child (grid).

order

Responsive<number | `${number}`>

—

Flex/grid child reorder index.

asChild

boolean

—

When `true`, renders the primitive's single React child via `Slot`, forwarding className/style/ref/event handlers onto it.

as

ElementType

"div"

Rendered intrinsic element or component.

ref

ForwardedRef<Element>

—

Recipes

For most row/column layouts prefer Inline or Stack — they’re Flex with fewer knobs and clearer intent.
“Stack on mobile, side-by-side on desktop”: <Flex direction={{ base: 'column', md: 'row' }} gap="4" />.
App shell main area: <Flex direction="column" flex="1" minHeight="0" /> so a nested scroll area can claim the remaining height.