useResponsiveGrid

Docs

useResponsiveGrid

Layout helper that returns responsive column counts and item sizing for adaptive masonry or grid layouts.

Installation

pnpm dlx uselab@latest add use-responsive-grid

Usage

import * as React from "react"
 
import { useResponsiveGrid } from "@/hooks/use-responsive-grid"
 
const breakpoints = [
  { minWidth: 0, columns: 1 },
  { minWidth: 640, columns: 2 },
  { minWidth: 900, columns: 3 },
  { minWidth: 1200, columns: 4 },
]
 
export function Gallery() {
  const { columns, itemStyle, containerStyle } = useResponsiveGrid({
    breakpoints,
    gap: 24,
    layout: "masonry",
  })
 
  return (
    <div style={containerStyle}>
      {Array.from({ length: 8 }).map((_, index) => (
        <div key={index} style={itemStyle} className="rounded-md bg-muted p-4">
          Item {index + 1}
        </div>
      ))}
    </div>
  )
}

API Reference

Parameters

Name	Type	Description	Default Value	Optional
`breakpoints`	`ResponsiveBreakpoint[]`	Array of `{ minWidth, columns }` rules, evaluated from smallest to largest screen width.	—	No
`gap`	`number`	Gap between grid items (in pixels).	`16`	Yes
`defaultColumns`	`number`	Fallback column count for SSR or widths below the first breakpoint.	`1`	Yes
`layout`	`"flex" \| "masonry"`	Choose between a flex-based grid or CSS column masonry layout.	`"flex"`	Yes

Return Values

Name	Type	Description
`columns`	`number`	Current number of columns that match the viewport width.
`gap`	`number`	Gap passed to the hook.
`layout`	`"flex" \| "masonry"`	Currently applied layout mode.
`containerStyle`	`React.CSSProperties`	Styles to spread on the outer wrapper (flex or column masonry).
`itemStyle`	`React.CSSProperties`	Styles for each item (width/flex for grid, break-inside for masonry).

Breakpoint Tips

Breakpoints are sorted automatically, so you can pass them in any order.
Each breakpoint represents the minimum width where the column count becomes active.
Always provide a baseline rule (e.g., { minWidth: 0, columns: 1 }) to guarantee a valid layout.
When used with flexbox, ensure your container uses display: flex and flex-wrap: wrap to honor item widths.
For CSS Grid layouts, you can still use columns to derive grid-template-columns: repeat(columns, minmax(0, 1fr)).

Examples

Masonry-style gallery

const { columns, itemStyle, gap } = useResponsiveGrid({
  breakpoints: [
    { minWidth: 0, columns: 1 },
    { minWidth: 768, columns: 2 },
    { minWidth: 1024, columns: 3 },
  ],
  gap: 18,
})
 
return (
  <div style={containerStyle}>
    {photos.map((photo) => (
      <figure key={photo.id} style={itemStyle}>
        <img src={photo.src} alt={photo.alt} className="w-full rounded-lg" />
      </figure>
    ))}
  </div>
)

Dashboard cards

const { columns, containerStyle, itemStyle } = useResponsiveGrid({
  breakpoints: [
    { minWidth: 0, columns: 1 },
    { minWidth: 600, columns: 2 },
    { minWidth: 900, columns: 3 },
  ],
})
 
return (
  <div
    style={{
      ...containerStyle,
      display: "grid",
      gap: 16,
      gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
    }}
  >
    {widgets.map((widget) => (
      <Widget key={widget.id} data={widget} style={itemStyle} />
    ))}
  </div>
)

Custom gaps per theme

const gap = useIsCompactMode() ? 12 : 24
const { containerStyle, itemStyle } = useResponsiveGrid({ breakpoints, gap })
 
return (
  <div style={containerStyle}>
    {items.map((item) => (
      <Card key={item.id} style={itemStyle} />
    ))}
  </div>
)

Notes

The hook runs both on mount and on every resize; avoid passing unstable breakpoint arrays (wrap them in useMemo if needed).
Works in SSR environments by falling back to defaultColumns until the client width is known.
itemStyle uses calc() to subtract gaps, ensuring items fill the row without overflow.
You can combine the returned columns with CSS Grid templates for traditional grids, or use itemStyle with flexbox for masonry-style layouts.

useRerender useSafeState

On This Page

Installation
Usage
API Reference
- Parameters
- Return Values
Breakpoint Tips
Examples
Notes

Contribute

Docs

useResponsiveGrid

Layout helper that returns responsive column counts and item sizing for adaptive masonry or grid layouts.

Playground

Experiment with gap, default columns and breakpoint presets to see how the hook responds.

Breakpoint Preset

Default Columns (SSR / narrow widths)

Layout Mode

Masonry uses CSS columns (`break-inside: avoid`) to achieve true staggered heights.

Gap: 20pxDrag to simulate dense vs roomy layouts

Active breakpoints

≥ 0px → 1 column
≥ 640px → 2 columns
≥ 900px → 3 columns
≥ 1200px → 4 columns

Responsive Grid

Layout adapts from 1 to 4 columns depending on viewport width.

1 Flex columns

Gap: 20px

Nature

Sunset Boulevard

Golden hour across the bay

Item width: 100%

Adventure

Mountain Steps

Switchbacks leading to the summit

Item width: 100%

City

Urban Lights

Neon reflections after rain

Item width: 100%

Lifestyle

Coffee Ritual

Pour-over morning routine

Item width: 100%

Travel

Desert Horizon

Minimal dunes at dusk

Item width: 100%

Design

Glass Facade

Patterns in modern architecture

Item width: 100%

Installation

pnpm dlx uselab@latest add use-responsive-grid

Usage

import * as React from "react"
 
import { useResponsiveGrid } from "@/hooks/use-responsive-grid"
 
const breakpoints = [
  { minWidth: 0, columns: 1 },
  { minWidth: 640, columns: 2 },
  { minWidth: 900, columns: 3 },
  { minWidth: 1200, columns: 4 },
]
 
export function Gallery() {
  const { columns, itemStyle, containerStyle } = useResponsiveGrid({
    breakpoints,
    gap: 24,
    layout: "masonry",
  })
 
  return (
    <div style={containerStyle}>
      {Array.from({ length: 8 }).map((_, index) => (
        <div key={index} style={itemStyle} className="rounded-md bg-muted p-4">
          Item {index + 1}
        </div>
      ))}
    </div>
  )
}

API Reference

Parameters

Name	Type	Description	Default Value	Optional
`breakpoints`	`ResponsiveBreakpoint[]`	Array of `{ minWidth, columns }` rules, evaluated from smallest to largest screen width.	—	No
`gap`	`number`	Gap between grid items (in pixels).	`16`	Yes
`defaultColumns`	`number`	Fallback column count for SSR or widths below the first breakpoint.	`1`	Yes
`layout`	`"flex" \| "masonry"`	Choose between a flex-based grid or CSS column masonry layout.	`"flex"`	Yes

Return Values

Name	Type	Description
`columns`	`number`	Current number of columns that match the viewport width.
`gap`	`number`	Gap passed to the hook.
`layout`	`"flex" \| "masonry"`	Currently applied layout mode.
`containerStyle`	`React.CSSProperties`	Styles to spread on the outer wrapper (flex or column masonry).
`itemStyle`	`React.CSSProperties`	Styles for each item (width/flex for grid, break-inside for masonry).

Breakpoint Tips

Breakpoints are sorted automatically, so you can pass them in any order.
Each breakpoint represents the minimum width where the column count becomes active.
Always provide a baseline rule (e.g., { minWidth: 0, columns: 1 }) to guarantee a valid layout.
When used with flexbox, ensure your container uses display: flex and flex-wrap: wrap to honor item widths.
For CSS Grid layouts, you can still use columns to derive grid-template-columns: repeat(columns, minmax(0, 1fr)).

Examples

Masonry-style gallery

const { columns, itemStyle, gap } = useResponsiveGrid({
  breakpoints: [
    { minWidth: 0, columns: 1 },
    { minWidth: 768, columns: 2 },
    { minWidth: 1024, columns: 3 },
  ],
  gap: 18,
})
 
return (
  <div style={containerStyle}>
    {photos.map((photo) => (
      <figure key={photo.id} style={itemStyle}>
        <img src={photo.src} alt={photo.alt} className="w-full rounded-lg" />
      </figure>
    ))}
  </div>
)

Dashboard cards

const { columns, containerStyle, itemStyle } = useResponsiveGrid({
  breakpoints: [
    { minWidth: 0, columns: 1 },
    { minWidth: 600, columns: 2 },
    { minWidth: 900, columns: 3 },
  ],
})
 
return (
  <div
    style={{
      ...containerStyle,
      display: "grid",
      gap: 16,
      gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
    }}
  >
    {widgets.map((widget) => (
      <Widget key={widget.id} data={widget} style={itemStyle} />
    ))}
  </div>
)

Custom gaps per theme

const gap = useIsCompactMode() ? 12 : 24
const { containerStyle, itemStyle } = useResponsiveGrid({ breakpoints, gap })
 
return (
  <div style={containerStyle}>
    {items.map((item) => (
      <Card key={item.id} style={itemStyle} />
    ))}
  </div>
)

Notes

The hook runs both on mount and on every resize; avoid passing unstable breakpoint arrays (wrap them in useMemo if needed).
Works in SSR environments by falling back to defaultColumns until the client width is known.
itemStyle uses calc() to subtract gaps, ensuring items fill the row without overflow.
You can combine the returned columns with CSS Grid templates for traditional grids, or use itemStyle with flexbox for masonry-style layouts.

useRerender useSafeState

On This Page

Installation
Usage
API Reference
- Parameters
- Return Values
Breakpoint Tips
Examples
Notes

Contribute