Skip to content

Latest commit

 

History

History
executable file
·
636 lines (497 loc) · 30.8 KB

README.md

File metadata and controls

executable file
·
636 lines (497 loc) · 30.8 KB
Raw

npm i @dash-ui/react-layout

Bundlephobia Types Code coverage Build status NPM Version MIT License

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