GitHub - dash-ui/react-layout: Layout primitives for React and @dash-ui, including Box, Cluster, Grid, Row, Column, and Layer.

npm i @dash-ui/react-layout

Features

Comprehensive grids, rows, columns, and more.
Responsive props add breakpoint-specific styles to your layout components.
CSS variable themes mean performance is never going to be an issue when users switch from light to dark mode.
Strong types even when you use an as prop. If it's a button, you're going to be limited to <button> HTML attributes!
Tiny (<3.5kB) as layout primitive libraries go

Quick start

Check out an example on CodeSandbox

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 <Box>
  color: {
    primary: "#ee5b5f",
  },
  // "elevation" is used for the "elevation" prop on <Box>
  // 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 = () => (
  <LayoutProvider
    styles={styles}
    mediaQueries={{
      sm: "only screen and (min-width: 0em)",
      md: "only screen and (min-width: 35em)",
      lg: "only screen and (min-width: 80em)",
    }}
  >
    <Component />
  </LayoutProvider>
);

const Component = () => (
  // Responsive props are opt-in. In order to use them
  // you have to define a "mediaQueries" prop on your
  // <LayoutProvider>
  <Box size={300} pad={{ sm: "md", md: "lg" }}>
    Hello world
  </Box>
);

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()`	Returns the responsive `styles` 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	Learn how to add types to responsive props
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

import * as React from "react";
import { styles } from "@dash-ui/styles";
import { LayoutProvider, Box } from "@dash-ui/react-layout";

const styles = createStyles();

const App = () => (
  <LayoutProvider
    styles={styles}
    mediaQueries={{
      sm: "only screen and (min-width: 0em)",
      md: "only screen and (min-width: 35em)",
      lg: "only screen and (min-width: 80em)",
    }}
  >
    <Component />
  </LayoutProvider>
);

const Component = () => (
  // Responsive props are opt-in. In order to use them
  // you have to define a "mediaQueries" prop on your
  // <LayoutProvider>
  <Box size={300} pad={{ sm: "md", md: "lg" }}>
    Hello world
  </Box>
);

Props

Prop	Type	Default	Required?	Description
styles	`Styles<DashTokens, DashThemes>`	`styles`	No	The `styles` instance you're using to create styles. By default this is the `styles` instance exported from `@dash-ui/styles`
mediaQueries	`Record<string, string>`		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

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
  // <LayoutProvider>
  <Box size={300} pad={{ sm: "md", md: "lg" }}>
    Hello world
  </Box>
);

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<number \| string>`	No	Sets a `width` CSS property on your component.
height	`ResponsiveProp<number \| string>`	No	Sets a `height` CSS property on your component.
size	`ResponsiveProp<number \| string>`	No	Sets a `size` CSS property on your component.
pad	`ResponsiveProp<keyof DashTokens['pad'] \| (keyof DashTokens['pad'])[]>`	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<keyof DashTokens['color']>`	No	Sets a `background-color` CSS property on your component using the "color" token in your theme.
elevation	`ResponsiveProp<keyof DashTokens['elevation']>`	No	Sets a `box-shadow` CSS property on your component using the "elevation" token in your theme.
radius	`ResponsiveProp<keyof DashTokens['radius'] \| (keyof DashTokens['radius'])[]>`	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

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
  // <LayoutProvider>
  <Cluster width={{ sm: "100%", md: 400 }} gap={{ sm: "sm", md: "md" }}>
    <Box bg="primary" width={100} height={24} radius="md" />
    <Box bg="primary" width={140} height={24} radius="md" />
    <Box bg="primary" width={80} height={24} radius="md" />
    <Box bg="primary" width={90} height={24} radius="md" />
  </Cluster>
);

Props

🔆 In addition to the props below, <Row> inherits all props from <Box>.

Name	Type	Required?	Description
gap	`ResponsiveProp<keyof DashTokens['gap']>`	No	Sets a vertical and horizontal gap between the child elements in the cluster using the "gap" token in your theme.
reverse	`ResponsiveProp<boolean>`	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

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
  // <LayoutProvider>
  <Column width="100%" gap={{ sm: "sm", md: "md" }}>
    <Box bg="primary" height={100} width="100%" radius="md" />
    <Box bg="primary" height={140} width="100%" radius="md" />
    <Box bg="primary" height={80} width="100%" radius="md" />
    <Box bg="primary" height={90} width="100%" radius="md" />
  </Column>
);

Props

🔆 In addition to the props below, <Column> inherits all props from <Box>.

Name	Type	Required?	Description
gap	`ResponsiveProp<keyof DashTokens['gap']>`	No	Sets a vertical gap between its child elements using the "gap" token in your theme.
reverse	`ResponsiveProp<boolean>`	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

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
  // <LayoutProvider>
  <Row align="start" width="100%" gap={{ sm: "sm", md: "md" }}>
    {/* This item will be aligned in the center */}
    <FlexItem
      align="center"
      bg="primary"
      width={100}
      height={120}
      radius="md"
    />
    {/* These will both align at flex-start */}
    <Box bg="primary" width={140} height={140} radius="md" />
    <Box bg="primary" width={80} height={124} radius="md" />
  </Row>
);

Props

🔆 In addition to the props below, <FlexItem> 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<number \| string>`	No	Sets a `flex-basis` CSS property on your component.
grow	`ResponsiveProp<boolean \| number>`	No	Sets a `flex-grow` CSS property on your component.
maxWidth	`ResponsiveProp<number \| string>`	No	Sets a `max-width` CSS property on your component.
maxHeight	`ResponsiveProp<number \| string>`	No	Sets a `max-height` CSS property on your component.
order	`ResponsiveProp<number>`	No	Sets a `order` CSS property on your component.
shrink	`ResponsiveProp<boolean \| number>`	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

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
  // <LayoutProvider>
  <Grid cols={3} rows={3} gap={{ sm: "sm", md: "md" }}>
    <Box bg="primary" height={100} radius="md" />
    <Box bg="primary" height={100} radius="md" />
    <Box bg="primary" height={100} radius="md" />
    <Box bg="primary" height={100} radius="md" />
    <Box bg="primary" height={100} radius="md" />
    <Box bg="primary" height={100} radius="md" />
    <Box bg="primary" height={100} radius="md" />
    <Box bg="primary" height={100} radius="md" />
    <Box bg="primary" height={100} radius="md" />
  </Grid>
);

Props

🔆 In addition to the props below, <Grid> 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<number \| (number \| string)[]>`	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<boolean>`	No	Makes the component display as an `inline-grid` rather than `grid`.
rows	`ResponsiveProp<number \| (number \| string)[]>`	No	Sets a `grid-template-rows` CSS property on your component.

GapProp

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

import * as React from "react";
import { Grid, GridItem, Box } from "@dash-ui/react-layout";

const Component = () => (
  <Grid cols={3} rows={[100, 100]} gap={{ sm: "sm", md: "md" }}>
    {/* This item spans 3 columns */}
    <GridItem bg="primary" colStart={1} colEnd={4} radius="md" />
    <Box bg="primary" radius="md" />
    <Box bg="primary" radius="md" />
    <Box bg="primary" radius="md" />
  </Grid>
);

Props

🔆 In addition to the props below, <GridItem> 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<number \| string>`	No	Sets a `grid-column-start` CSS property on your component.
colEnd	`ResponsiveProp<number \| string>`	No	Sets a `grid-column-end` CSS property on your component.
rowStart	`ResponsiveProp<number \| string>`	No	Sets a `grid-row-start` CSS property on your component.
rowEnd	`ResponsiveProp<number \| string>`	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

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
  // <LayoutProvider>
  <Layer width={600} height={600}>
    <LayerItem placement="bottomRight" bg="primary" size={64} radius="md" />
    <LayerItem placement="topLeft" bg="primary" size={64} radius="md" />
  </Layer>
);

Props

🔆 <Layer> 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

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
  // <LayoutProvider>
  <Layer width={400} height={400}>
    <LayerItem placement="bottomRight" bg="primary" size={64} radius="md" />
    <LayerItem placement="topLeft" bg="primary" size={64} radius="md" />
  </Layer>
);

Props

🔆 In addition to the props below, <LayerItem> inherits all props from <Box>.

Name	Type	Required?	Description
offset	`ResponsiveProp<number \| string>`	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`.
z	`ResponsiveProp<number>`	No	Sets a `z-index` CSS property on your component.

Placements

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

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
  // <LayoutProvider>
  <Row width="100%" gap={{ sm: "sm", md: "md" }}>
    <Box bg="primary" width={100} height={120} radius="md" />
    <Box bg="primary" width={140} height={140} radius="md" />
    <Box bg="primary" width={80} height={124} radius="md" />
    <Box bg="primary" width={90} height={96} radius="md" />
  </Row>
);

Props

🔆 In addition to the props below, <Row> inherits all props from <Box>.

Name	Type	Required?	Description
gap	`ResponsiveProp<keyof DashTokens['gap']>`	No	Sets a horizontal gap between its child elements using the "gap" token in your theme.
reverse	`ResponsiveProp<boolean>`	No	Reverses the direction of the column to right-to-left

Hooks

useResponsiveStyles()

Returns the responsive styles used for creating responsive layout props.

Returns

// See https://github.com/dash-ui/responsive
ResponsiveStyles<DashTokens, MediaQueries, DashThemeNames>

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

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 101 Commits
.github		.github
.husky		.husky
src		src
test		test
types		types
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
lundle.config.js		lundle.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

License

dash-ui/react-layout

Folders and files

Latest commit

History

Repository files navigation

Features

Quick start

API docs

Components

Hooks

TypeScript support

Components

<LayoutProvider>

Example

Props

<Box>

Example

Props

<Cluster>

Example

Props

<Column>

Example

Props

<FlexItem>

Example

Props

<Grid>

Example

Props

GapProp

<GridItem>

Example

Props

<Layer>

Example

Props

<LayerItem>

Example

Props

Placements

<Row>

Example

Props

Hooks

useResponsiveStyles()

Returns

TypeScript Support

Strongly typed media queries

Strongly typed tokens

LICENSE

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 4

Packages 0

Contributors 2

Languages

Packages