@vitus-labs/coolgrid

@vitus-labs/coolgrid

Responsive grid system for React.

Bootstrap-inspired Container / Row / Col grid with context-cascading configuration. Define breakpoints, column count, gaps, and gutters at any level — children inherit automatically. Every value is responsive.

Features

• Familiar mental model — Container, Row, Col just like Bootstrap
• Context cascading — set columns, gaps, and gutters at Container level, inherited by all Rows and Cols
• Responsive values — single value, mobile-first array, or breakpoint object on every prop
• Custom breakpoints — name and size them however you want
• Custom column counts — 12, 24, 5 — any number
• Custom components — swap Container, Row, or Col underlying elements
• Default Bootstrap theme — included and ready to use

Installation

npm install @vitus-labs/coolgrid @vitus-labs/core @vitus-labs/unistyle

Quick Start

import { Container, Row, Col, Provider, theme } from '@vitus-labs/coolgrid'

const App = () => (
  <Provider theme={theme}>
    <Container>
      <Row>
        <Col size={8}>Main content</Col>
        <Col size={4}>Sidebar</Col>
      </Row>
    </Container>
  </Provider>
)

Components

Container

Outermost grid boundary. Sets max-width and provides configuration context to descendants.

<Container
  columns={12}
  gap={16}
  gutter={24}
  padding={16}
>
  <Row>...</Row>
</Container>

Prop	Type	Description
columns	number	Number of grid columns (default: 12)
gap	number	Space between columns
gutter	number	Outer gutter (negative margin offset on Row)
padding	number	Column inner padding
width	value | function	Override container max-width
component	ComponentType	Custom root element
css	ExtendCss	Extend container styling
contentAlignX	AlignX	Horizontal alignment of columns

All configuration props cascade to Row and Col through context.

Row

Flex wrapper with column management. Inherits Container config and can override it.

<Row
  size={{ xs: 12, md: 6 }}
  contentAlignX="center"
>
  <Col>Column 1</Col>
  <Col>Column 2</Col>
</Row>

Setting size on Row applies it to all Cols inside:

// All columns are 6 of 12
<Row size={6}>
  <Col>Half</Col>
  <Col>Half</Col>
</Row>

Prop	Type	Description
size	number	Default column size for all Cols inside
component	ComponentType	Custom row element
css	ExtendCss	Extend row styling
contentAlignX	AlignX	Override horizontal alignment

Col

Individual column. Width is calculated as a fraction of total columns.

// Fixed size
<Col size={4}>1/3 width</Col>

// Responsive size
<Col size={{ xs: 12, sm: 6, lg: 4 }}>
  Full on mobile, half on small, third on large
</Col>

// Hidden on mobile
<Col size={{ xs: 0, md: 6 }}>Hidden on xs</Col>

Prop	Type	Description
size	number	Column span (e.g. 4 of 12)
padding	number	Override column inner padding
component	ComponentType	Custom column element
css	ExtendCss	Extend column styling

Configuration

Custom Breakpoints

<Provider theme={{
  rootSize: 16,
  breakpoints: {
    phone: 0,
    tablet: 600,
    desktop: 1024,
    wide: 1440,
  },
}}>

Custom Column Count

<Container columns={24}>
  <Row>
    <Col size={16}>Two thirds</Col>
    <Col size={8}>One third</Col>
  </Row>
</Container>

Custom Container Widths

<Provider theme={{
  rootSize: 16,
  breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
  grid: {
    columns: 12,
    container: {
      xs: '100%',
      sm: 540,
      md: 720,
      lg: 960,
      xl: 1140,
    },
  },
}}>

Context Cascading

Configuration flows from Container through Row to Col via React context:

Container (columns: 12, gap: 16)
  └─ Row (inherits columns, gap)
       └─ Col (inherits columns, gap, calculates width)

Props set on a child override the inherited value for that level and below.

Default Theme

The included theme export provides Bootstrap 4 defaults:

{
  rootSize: 16,
  breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
  grid: {
    columns: 12,
    container: { xs: '100%', sm: 540, md: 720, lg: 960, xl: 1140 },
  },
}

Responsive Values

All numeric props support three formats:

// Single value
<Col size={6} />

// Array (mobile-first, by breakpoint position)
<Col size={[12, 6, 4]} />

// Object (explicit breakpoints)
<Col size={{ xs: 12, md: 6, lg: 4 }} />

React Native

Coolgrid includes native components (Col.native.tsx, Row.native.tsx) that use onLayout measurement instead of CSS calc(). Works automatically when initialized with @vitus-labs/connector-native.

Peer Dependencies

Package	Version
react	>= 19
@vitus-labs/core	*
@vitus-labs/unistyle	*
react-native	>= 0.76 (optional)

License

MIT