@dash-ui/react-layout v1.0.0

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

Hooks

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.

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

<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