https://github.com/dash-ui/react-layout
Layout primitives for React and @dash-ui, including Box, Cluster, Grid, Row, Column, and Layer.
https://github.com/dash-ui/react-layout
cluster css-in-js css-in-react css-in-ts dash dash-ui grid layer layout-components layout-primitives react-layout-components react-layout-primitives spacer-component stack-component
Last synced: about 1 month ago
JSON representation
Layout primitives for React and @dash-ui, including Box, Cluster, Grid, Row, Column, and Layer.
- Host: GitHub
- URL: https://github.com/dash-ui/react-layout
- Owner: dash-ui
- License: mit
- Created: 2020-04-22T03:02:30.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2023-10-17T09:31:20.000Z (over 2 years ago)
- Last Synced: 2025-08-08T12:58:57.824Z (10 months ago)
- Topics: cluster, css-in-js, css-in-react, css-in-ts, dash, dash-ui, grid, layer, layout-components, layout-primitives, react-layout-components, react-layout-primitives, spacer-component, stack-component
- Language: TypeScript
- Homepage:
- Size: 1.52 MB
- Stars: 8
- Watchers: 1
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
>
```sh
npm i @dash-ui/react-layout
```
---
## Features
- [x] **Comprehensive** grids, rows, columns, and more.
- [x] **Responsive props** add breakpoint-specific styles to your layout components.
- [x] **CSS variable themes** mean performance is never going to be an issue when
users switch from light to dark mode.
- [x] **Strong types** even when you use an `as` prop. If it's a button, you're
going to be limited to `` HTML attributes!
- [x] **Tiny** ([<3.5kB](https://bundlephobia.com/result?p=@dash-ui/react-layout@latest)) as layout primitive libraries go
## Quick start
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-example-3m3rg?file=/src/App.tsx)
```jsx harmony
import * as React from "react";
import { createStyles } from "@dash-ui/styles";
import { LayoutProvider, Box } from "@dash-ui/react-layout";
// These root variable tokens are required in order to access
// all features of @dash-ui/react-layout
const tokens = {
// "color" is used for the "bg" prop on
color: {
primary: "#ee5b5f",
},
// "elevation" is used for the "elevation" prop on
// It adds a box shadow to components
elevation: {
sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
md: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
},
// "pad" is used for the "pad" prop
// It adds padding to components
pad: {
sm: "0.5rem",
md: "1rem",
lg: "2rem",
},
// "gap" is used for the "gap" prop
// It adds margins between child components
gap: {
sm: "0.25rem",
md: "0.5rem",
lg: "1rem",
},
// "radius" is used for the "radius" prop
// It adds border-radius to components
radius: {
sm: "0.125rem",
md: "0.25rem",
},
};
const styles = createStyles({
tokens,
});
const App = () => (
);
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
Hello world
);
```
## API docs
### Components
| Component | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [``](#layoutprovider) | A context provider which is only required if you intend on using responsive props or a custom `styles` instance. |
| [``](#box) | A layout component for adding size, padding, position, color, and more using tokens from your CSS variable theme. |
| [``](#cluster) | A row directional layout component that distributes its items in a cluster. Common use cases are tags and input chips. |
| [``](#column) | A layout component that distributes its items in a column without wrapping or shrinking. |
| [``](#flexitem) | A layout component that can add positioning properties to itself inside of a flex container. |
| [``](#grid) | A layout component that distributes its children in a grid. This an abstraction of CSS grids. |
| [``](#griditem) | A layout component that can add positioning properties to itself inside of a [``](#grid) component. |
| [``](#layer) | A layout component that is a container for [``](#layeritem)s. |
| [``](#layeritem) | A layout component than positions itself absolutely inside of its container in whichever placement you decide. |
| [``](#row) | A layout component that distributes its items in a row without wrapping. |
### Hooks
| Component | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [`useResponsiveStyles()`](#useresponsivestyles) | Returns the [responsive `styles`](https://github.com/dash-ui/responsive) used for creating responsive layout props. |
### TypeScript support
`@dash-ui/react-layout` is written in TypeScript. That said, there are some things to know
as it relates to connecting your `DashTokens` and media query types to these layout
components.
| | Description |
| ------------------------------------------------------------- | ------------------------------------------ |
| [Strongly typed media queries](#strongly-typed-media-queries) | Learn how to add types to responsive props |
| [Strongly typed tokens](#strongly-typed-tokens) | Learn how to add types to your CSS tokens |
---
## Components
### <LayoutProvider>
A context provider which is only required if you intend on using media query
props or a custom `styles` instance.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-example-3m3rg?file=/src/App.tsx)
```tsx
import * as React from "react";
import { styles } from "@dash-ui/styles";
import { LayoutProvider, Box } from "@dash-ui/react-layout";
const styles = createStyles();
const App = () => (
);
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
Hello world
);
```
#### Props
| Prop | Type | Default | Required? | Description |
| ------------ | -------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| styles | `Styles` | `styles` | No | The `styles` instance you're using to create styles. By default this is the `styles` instance exported from [`@dash-ui/styles`](https://github.com/dash-ui/styles) |
| mediaQueries | `Record` | | No | A mapping of name/media query pairs. This is only required if youre' using responsive props. |
### <Box>
A layout component for adding size, padding, position, color, and more using tokens
from your CSS variable theme.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-box-example-tpsky?file=/src/App.tsx)
```tsx
import * as React from "react";
import { Box } from "@dash-ui/react-layout";
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
Hello world
);
```
#### Props
| Name | Type | Required? | Description |
| --------- | ------------------------------------------------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| display | `ResponsiveProp<'flex' \| 'inlineFlex' \| 'block' \| 'inlineBlock' \| 'inline' \| 'none'>` | No | Sets a `display` CSS property on your component. |
| position | `ResponsiveProp<'relative' \| 'absolute' \| 'sticky' \| 'fixed'>` | No | Sets a `position` CSS property on your component. |
| width | `ResponsiveProp` | No | Sets a `width` CSS property on your component. |
| height | `ResponsiveProp` | No | Sets a `height` CSS property on your component. |
| size | `ResponsiveProp` | No | Sets a `size` CSS property on your component. |
| pad | `ResponsiveProp` | No | Sets a `padding` CSS property on your component using the "pad" token in your theme. When this is an array padding will be joined in the same order as the `padding` CSS property i.e. `['sm', 'md']` would be `padding: var(--pad-sm) var(--pad-md)`. |
| bg | `ResponsiveProp` | No | Sets a `background-color` CSS property on your component using the "color" token in your theme. |
| elevation | `ResponsiveProp` | No | Sets a `box-shadow` CSS property on your component using the "elevation" token in your theme. |
| radius | `ResponsiveProp` | No | Sets a `border-radius` CSS property on your component using the "radius" token in your theme. When this is an array padding will be joined in the same order as the `border-radius` CSS property i.e. `['sm', 'md']` would be `border-radius: var(--radius-sm) var(--radius-md)`. |
| className | `string \| string[]` | No | Adds one or several class names to your component. |
### <Cluster>
A row directional layout component that distributes its items in
a cluster. Common use cases are tags and input chips.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-cluster-example-y0p5c?file=/src/App.tsx)
```tsx
import * as React from "react";
import { Cluster, Box } from "@dash-ui/react-layout";
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
);
```
#### Props
> 🔆 In addition to the props below, `` inherits all props from [``](#box).
| Name | Type | Required? | Description |
| ------- | ----------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| gap | `ResponsiveProp` | No | Sets a vertical and horizontal gap between the child elements in the cluster using the "gap" token in your theme. |
| reverse | `ResponsiveProp` | No | Reverses the direction of your cluster so that it lays out right-to-left. |
### <Column>
A layout component that distributes its items in a column without wrapping
or shrinking.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-column-example-e81yl?file=/src/App.tsx)
```tsx
import * as React from "react";
import { Column, Box } from "@dash-ui/react-layout";
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
);
```
#### Props
> 🔆 In addition to the props below, `` inherits all props from [``](#box).
| Name | Type | Required? | Description |
| ------- | ----------------------------------------- | --------- | ----------------------------------------------------------------------------------- |
| gap | `ResponsiveProp` | No | Sets a vertical gap between its child elements using the "gap" token in your theme. |
| reverse | `ResponsiveProp` | No | Reverses the direction of the column to bottom-to-top |
### <FlexItem>
A layout component that can add positioning properties to itself inside of
a flex container.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-flexitem-example-mbmu2?file=/src/App.tsx)
```tsx
import * as React from "react";
import { FlexItem, Box, Row } from "@dash-ui/react-layout";
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
{/* This item will be aligned in the center */}
{/* These will both align at flex-start */}
);
```
#### Props
> 🔆 In addition to the props below, `` inherits all props from [``](#box).
| Name | Type | Required? | Description |
| --------- | ------------------------------------------------------------------------- | --------- | ---------------------------------------------------- |
| align | `ResponsiveProp<'start' \| 'end' \| 'center' \| 'baseline' \| 'stretch'>` | No | Sets a `align-self` CSS property on your component. |
| basis | `ResponsiveProp` | No | Sets a `flex-basis` CSS property on your component. |
| grow | `ResponsiveProp` | No | Sets a `flex-grow` CSS property on your component. |
| maxWidth | `ResponsiveProp` | No | Sets a `max-width` CSS property on your component. |
| maxHeight | `ResponsiveProp` | No | Sets a `max-height` CSS property on your component. |
| order | `ResponsiveProp` | No | Sets a `order` CSS property on your component. |
| shrink | `ResponsiveProp` | No | Sets a `flex-shrink` CSS property on your component. |
### <Grid>
A layout component that distributes its children in a grid. This an abstraction
of CSS grids.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-grid-example-okqnz?file=/src/App.tsx)
```tsx
import * as React from "react";
import { Grid, Box } from "@dash-ui/react-layout";
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
);
```
#### Props
> 🔆 In addition to the props below, `` inherits all props from [``](#box),
> omitting `display` which is always `"grid"`.
| Name | Type | Required? | Description |
| ----------- | ------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------- |
| alignX | `ResponsiveProp<'start' \| 'center' \| 'end' \| 'stretch'>` | No | Sets a `justify-items` CSS property on your component. |
| alignY | `ResponsiveProp<'start' \| 'center' \| 'end' \| 'stretch'>` | No | Sets a `align-items` CSS property on your component. |
| cols | `ResponsiveProp` | No | Sets a `grid-template-columns` CSS property on your component. |
| distributeX | `ResponsiveProp<'start' \| 'center' \| 'end' \| 'stretch' \| 'around' \| 'between' \| 'evenly'>` | No | Sets a `justify-content` CSS property on your component. |
| distributeY | `ResponsiveProp<'start' \| 'center' \| 'end' \| 'stretch' \| 'around' \| 'between' \| 'evenly'>` | No | Sets a `align-content` CSS property on your component. |
| gap | [`ResponsiveProp`](#gapprop) | No | Sets a horizontal and vertical gap between the child elements in the row using the "gap" token in your theme. |
| inline | `ResponsiveProp` | No | Makes the component display as an `inline-grid` rather than `grid`. |
| rows | `ResponsiveProp` | No | Sets a `grid-template-rows` CSS property on your component. |
#### GapProp
```typescript
type GapProp =
| keyof DashTokens["gap"]
| [keyof DashTokens["gap"], keyof DashTokens["gap"]];
```
### <GridItem>
A layout component that can add positioning properties to itself inside of
a [``](#grid) component.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-griditem-example-c1tc7?file=/src/App.tsx)
```tsx
import * as React from "react";
import { Grid, GridItem, Box } from "@dash-ui/react-layout";
const Component = () => (
{/* This item spans 3 columns */}
);
```
#### Props
> 🔆 In addition to the props below, `` inherits all props from [``](#box).
| Name | Type | Required? | Description |
| -------- | ----------------------------------------------------------- | --------- | ---------------------------------------------------------- |
| alignX | `ResponsiveProp<'start' \| 'center' \| 'end' \| 'stretch'>` | No | Sets a `justify-self` CSS property on your component. |
| alignY | `ResponsiveProp<'start' \| 'center' \| 'end' \| 'stretch'>` | No | Sets a `align-self` CSS property on your component. |
| colStart | `ResponsiveProp` | No | Sets a `grid-column-start` CSS property on your component. |
| colEnd | `ResponsiveProp` | No | Sets a `grid-column-end` CSS property on your component. |
| rowStart | `ResponsiveProp` | No | Sets a `grid-row-start` CSS property on your component. |
| rowEnd | `ResponsiveProp` | No | Sets a `grid-row-end` CSS property on your component. |
### <Layer>
A layout component that is a container for [``](#layeritem)s.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-layer-and-layeritem-example-we2by?file=/src/App.tsx)
```tsx
import * as React from "react";
import { Layer, LayerItem } from "@dash-ui/react-layout";
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
);
```
#### Props
> 🔆 `` inherits all of its props from [``](#box),
> omitting `position` which is always `"relative"`.
### <LayerItem>
A layout component than positions itself absolutely inside of its container
in whichever placement you decide.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-layer-and-layeritem-example-we2by?file=/src/App.tsx)
```tsx
import * as React from "react";
import { Layer, LayerItem } from "@dash-ui/react-layout";
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
);
```
#### Props
> 🔆 In addition to the props below, `` inherits all props from [``](#box).
| Name | Type | Required? | Description |
| --------- | ------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| offset | `ResponsiveProp` | No | Sets a `margin` between the edges of the layer item's container. |
| placement | [`ResponsiveProp`](#placements) | Yes | Sets the placement of your layer item relative to its container. See [`Placements`](#placements). |
| z | `ResponsiveProp` | No | Sets a `z-index` CSS property on your component. |
#### Placements
```typescript
type Placements =
| "top"
| "right"
| "bottom"
| "left"
| "center"
| "topLeft"
| "topRight"
| "bottomRight"
| "bottomLeft";
```
### <Row>
A layout component that distributes its items in a row without wrapping
or shrinking.
#### Example
[Check out an example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-row-example-ysvex?file=/src/App.tsx)
```tsx
import * as React from "react";
import { Row, Box } from "@dash-ui/react-layout";
const Component = () => (
// Responsive props are opt-in. In order to use them
// you have to define a "mediaQueries" prop on your
//
);
```
#### Props
> 🔆 In addition to the props below, `` inherits all props from [``](#box).
| Name | Type | Required? | Description |
| ------- | ----------------------------------------- | --------- | ------------------------------------------------------------------------------------- |
| gap | `ResponsiveProp` | No | Sets a horizontal gap between its child elements using the "gap" token in your theme. |
| reverse | `ResponsiveProp` | No | Reverses the direction of the column to right-to-left |
## Hooks
### useResponsiveStyles()
Returns the [responsive `styles`](https://github.com/dash-ui/responsive)
used for creating responsive layout props.
#### Returns
```typescript
// See https://github.com/dash-ui/responsive
ResponsiveStyles
```
## TypeScript Support
### Strongly typed media queries
To use media query types with `@dash-ui/react-layout`, you have to use the module declaration
pattern:
[Play with this example on **CodeSandbox**](https://codesandbox.io/s/dash-uireact-layout-example-3m3rg?file=/src/App.tsx)
```typescript
const mediaQueries = {
sm: "only screen and (min-width: 0em)",
md: "only screen and (min-width: 35em)",
lg: "only screen and (min-width: 80em)",
} as const;
type AppMediaQueries = typeof mediaQueries;
declare module "@dash-ui/react-layout" {
export interface MediaQueries extends AppMediaQueries {}
}
// OR alternatively
declare module "@dash-ui/react-layout" {
export interface MediaQueries {
sm: string;
md: string;
lg: string;
}
}
```
### Strongly typed tokens
To use variable types with `@dash-ui/react-layout`, you have to use the module declaration
pattern:
[Play with this example on **CodeSandbox**](https://codesandbox.io/s/dash-uistyles-strongly-typed-tokens-example-2-yk9bc?file=/src/App.tsx)
```typescript
const tokens = {
color: {
red: "#c17",
},
};
type AppTokens = typeof tokens;
declare module "@dash-ui/styles" {
export interface DashTokens extends AppTokens {}
}
// OR alternatively
declare module "@dash-ui/styles" {
export interface DashTokens {
color: {
red: string;
};
}
}
```
## LICENSE
MIT