npm i @dash-ui/react-layout

Features

• <input checked="" disabled="" type="checkbox"> Comprehensive grids, rows, columns, and more.
• <input checked="" disabled="" type="checkbox"> Responsive props add breakpoint-specific styles to your layout components.
• <input checked="" disabled="" type="checkbox"> CSS variable themes mean performance is never going to be an issue when

  users switch from light to dark mode.

• <input checked="" disabled="" type="checkbox"> Strong types even when you use an as prop. If it's a button, you're

  going to be limited to `<button>` HTML attributes!

• <input checked="" disabled="" type="checkbox"> Tiny (<3.5kB) as layout primitive libraries go

Quick start

Check out an example on CodeSandbox

`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 <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 />

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>`](#layoutprovider) | A context provider which is only required if you intend on using responsive props or a custom `styles` instance.       |
| [`<Box>`](#box)                       | A layout component for adding size, padding, position, color, and more using tokens from your CSS variable theme.      |
| [`<Cluster>`](#cluster)               | A row directional layout component that distributes its items in a cluster. Common use cases are tags and input chips. |
| [`<Column>`](#column)                 | A layout component that distributes its items in a column without wrapping or shrinking.                               |
| [`<FlexItem>`](#flexitem)             | A layout component that can add positioning properties to itself inside of a flex container.                           |
| [`<Grid>`](#grid)                     | A layout component that distributes its children in a grid. This an abstraction of CSS grids.                          |
| [`<GridItem>`](#griditem)             | A layout component that can add positioning properties to itself inside of a [`<Grid>`](#grid) component.              |
| [`<Layer>`](#layer)                   | A layout component that is a container for [`<LayerItem>`](#layeritem)s.                                               |
| [`<LayerItem>`](#layeritem)           | A layout component than positions itself absolutely inside of its container in whichever placement you decide.         |
| [`<Row>`](#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

### &lt;LayoutProvider&gt;

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 = () => (
  <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

<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

<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>.

<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>.

<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>.

<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".

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>.

<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>.

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>.

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

1.0.0 (2022-06-25)

Features

• release v1 (3c3e40a)
• remove alpha peers (b5e8dd5)
• update types and apis to support latest dash alpha (a75301d)

BREAKING CHANGES

• Types and expected input styles instance are updated to the latest alpha

1.0.0-alpha.2 (2022-06-25)

Features

• remove alpha peers (b5e8dd5)

1.0.0-alpha.1 (2021-10-29)

Features

• update types and apis to support latest dash alpha (a75301d)

BREAKING CHANGES

• Types and expected input styles instance are updated to the latest alpha

0.9.3 (2021-10-03)

Bug Fixes

• fix type errors (4926481)

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

0.9.2 (2021-02-16)

Features

• box: add z/inset props (fd89194)

0.9.1 (2021-02-16)

Features

• add more box properties (0610c90)

0.9.0 (2021-02-15)

⚠ BREAKING CHANGES

• Removes forwardRefAs util and AsProp type

Features

• upgrade forward-ref-as (5a9ceab)

0.8.5 (2021-01-01)

0.8.4 (2020-08-20)

Bug Fixes

• deps: upgrade forward-ref-as (f007b65)

0.8.3 (2020-08-10)

Bug Fixes

• box.tsx: fix forward ref type (d69dafe)

0.8.2 (2020-08-09)

0.8.1 (2020-08-09)

Bug Fixes

• fix memoization for lazy styles (b081446)

0.8.0 (2020-08-09)

⚠ BREAKING CHANGES

• useLayout() has been removed and useResponsiveStyles() has been added

• update @dash-ui/responsive (fd68ff6)

0.7.1 (2020-08-01)

0.7.0 (2020-07-31)

⚠ BREAKING CHANGES

• The LayoutContext value has been changed and several types have been updated

Bug Fixes

• layout: responsive props should always accept a "default" property (6f29c2f)

• replace mq() with @dash-ui/responsive (cb6d3e8)

0.6.1 (2020-07-27)

Bug Fixes

• layout: responsive props should always accept a "default" property (6f29c2f)

0.6.0 (2020-07-27)

⚠ BREAKING CHANGES

• Drops support for @dash-ui/styles@<0.8.0

• rename "variables" to "tokens" (1b2c23c)

0.5.2 (2020-07-24)

Bug Fixes

• utils: fix forwardRefAs ref type (b99eadf)

0.5.1 (2020-07-24)

Bug Fixes

• utils: fix forwardRefAs ref type (b99eadf)

0.5.0 (2020-07-24)

⚠ BREAKING CHANGES

• layoutcontext: The one() function has been replaced with cls() and no longer needs to be called in order to return a class name
• layout.tsx: Custom styles() instances must be provided directly to the <LayoutProvider>, as @dash-ui/react is no longer used

Features

• utils: add forwardRefAs utility (c8e31fa)

• layout.tsx: remove @dash-ui/react dependency (541af58)

• layoutcontext: replace "one" with "cls" in context (7213be9)

0.4.0 (2020-07-16)

⚠ BREAKING CHANGES

• deps-dev: Must be used with @dash-ui/styles@>=0.6.0 now

• deps-dev: upgrade @dash-ui/styles to 0.6.1 (9c93ed3)

0.3.0 (2020-07-04)