- Notifications
You must be signed in to change notification settings - Fork1
Layout primitives for React and@dash-ui, including Box, Cluster, Grid, Row, Column, and Layer.
License
NotificationsYou must be signed in to change notification settings
dash-ui/react-layout
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
npm i @dash-ui/react-layout
- 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 whenusers switch from light to dark mode.
- Strong types even when you use an
asprop. If it's a button, you'regoing to be limited to<button>HTML attributes! - Tiny (<3.5kB) as layout primitive libraries go
Check out an example onCodeSandbox
import*asReactfrom"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-layoutconsttokens={// "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 componentselevation:{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 componentspad:{sm:"0.5rem",md:"1rem",lg:"2rem",},// "gap" is used for the "gap" prop// It adds margins between child componentsgap:{sm:"0.25rem",md:"0.5rem",lg:"1rem",},// "radius" is used for the "radius" prop// It adds border-radius to componentsradius:{sm:"0.125rem",md:"0.25rem",},};conststyles=createStyles({ tokens,});constApp=()=>(<LayoutProviderstyles={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>);constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Boxsize={300}pad={{sm:"md",md:"lg"}}> Hello world</Box>);
| Component | Description |
|---|---|
<LayoutProvider> | A context provider which is only required if you intend on using responsive props or a customstyles 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. |
| Component | Description |
|---|---|
useResponsiveStyles() | Returns theresponsivestyles used for creating responsive layout props. |
@dash-ui/react-layout is written in TypeScript. That said, there are some things to knowas it relates to connecting yourDashTokens and media query types to these layoutcomponents.
| 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 |
A context provider which is only required if you intend on using media queryprops or a customstyles instance.
Check out an example onCodeSandbox
import*asReactfrom"react";import{styles}from"@dash-ui/styles";import{LayoutProvider,Box}from"@dash-ui/react-layout";conststyles=createStyles();constApp=()=>(<LayoutProviderstyles={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>);constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Boxsize={300}pad={{sm:"md",md:"lg"}}> Hello world</Box>);
| Prop | Type | Default | Required? | Description |
|---|---|---|---|---|
| styles | Styles<DashTokens, DashThemes> | styles | No | Thestyles instance you're using to create styles. By default this is thestyles 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. |
A layout component for adding size, padding, position, color, and more using tokensfrom your CSS variable theme.
Check out an example onCodeSandbox
import*asReactfrom"react";import{Box}from"@dash-ui/react-layout";constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Boxsize={300}pad={{sm:"md",md:"lg"}}> Hello world</Box>);
| Name | Type | Required? | Description |
|---|---|---|---|
| display | ResponsiveProp<'flex' | 'inlineFlex' | 'block' | 'inlineBlock' | 'inline' | 'none'> | No | Sets adisplay CSS property on your component. |
| position | ResponsiveProp<'relative' | 'absolute' | 'sticky' | 'fixed'> | No | Sets aposition CSS property on your component. |
| width | ResponsiveProp<number | string> | No | Sets awidth CSS property on your component. |
| height | ResponsiveProp<number | string> | No | Sets aheight CSS property on your component. |
| size | ResponsiveProp<number | string> | No | Sets asize CSS property on your component. |
| pad | ResponsiveProp<keyof DashTokens['pad'] | (keyof DashTokens['pad'])[]> | No | Sets apadding 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 thepadding CSS property i.e.['sm', 'md'] would bepadding: var(--pad-sm) var(--pad-md). |
| bg | ResponsiveProp<keyof DashTokens['color']> | No | Sets abackground-color CSS property on your component using the "color" token in your theme. |
| elevation | ResponsiveProp<keyof DashTokens['elevation']> | No | Sets abox-shadow CSS property on your component using the "elevation" token in your theme. |
| radius | ResponsiveProp<keyof DashTokens['radius'] | (keyof DashTokens['radius'])[]> | No | Sets aborder-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 theborder-radius CSS property i.e.['sm', 'md'] would beborder-radius: var(--radius-sm) var(--radius-md). |
| className | string | string[] | No | Adds one or several class names to your component. |
A row directional layout component that distributes its items ina cluster. Common use cases are tags and input chips.
Check out an example onCodeSandbox
import*asReactfrom"react";import{Cluster,Box}from"@dash-ui/react-layout";constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Clusterwidth={{sm:"100%",md:400}}gap={{sm:"sm",md:"md"}}><Boxbg="primary"width={100}height={24}radius="md"/><Boxbg="primary"width={140}height={24}radius="md"/><Boxbg="primary"width={80}height={24}radius="md"/><Boxbg="primary"width={90}height={24}radius="md"/></Cluster>);
🔆 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. |
A layout component that distributes its items in a column without wrappingor shrinking.
Check out an example onCodeSandbox
import*asReactfrom"react";import{Column,Box}from"@dash-ui/react-layout";constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Columnwidth="100%"gap={{sm:"sm",md:"md"}}><Boxbg="primary"height={100}width="100%"radius="md"/><Boxbg="primary"height={140}width="100%"radius="md"/><Boxbg="primary"height={80}width="100%"radius="md"/><Boxbg="primary"height={90}width="100%"radius="md"/></Column>);
🔆 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 |
A layout component that can add positioning properties to itself inside ofa flex container.
Check out an example onCodeSandbox
import*asReactfrom"react";import{FlexItem,Box,Row}from"@dash-ui/react-layout";constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Rowalign="start"width="100%"gap={{sm:"sm",md:"md"}}>{/* This item will be aligned in the center */}<FlexItemalign="center"bg="primary"width={100}height={120}radius="md"/>{/* These will both align at flex-start */}<Boxbg="primary"width={140}height={140}radius="md"/><Boxbg="primary"width={80}height={124}radius="md"/></Row>);
🔆 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 aalign-self CSS property on your component. |
| basis | ResponsiveProp<number | string> | No | Sets aflex-basis CSS property on your component. |
| grow | ResponsiveProp<boolean | number> | No | Sets aflex-grow CSS property on your component. |
| maxWidth | ResponsiveProp<number | string> | No | Sets amax-width CSS property on your component. |
| maxHeight | ResponsiveProp<number | string> | No | Sets amax-height CSS property on your component. |
| order | ResponsiveProp<number> | No | Sets aorder CSS property on your component. |
| shrink | ResponsiveProp<boolean | number> | No | Sets aflex-shrink CSS property on your component. |
A layout component that distributes its children in a grid. This an abstractionof CSS grids.
Check out an example onCodeSandbox
import*asReactfrom"react";import{Grid,Box}from"@dash-ui/react-layout";constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Gridcols={3}rows={3}gap={{sm:"sm",md:"md"}}><Boxbg="primary"height={100}radius="md"/><Boxbg="primary"height={100}radius="md"/><Boxbg="primary"height={100}radius="md"/><Boxbg="primary"height={100}radius="md"/><Boxbg="primary"height={100}radius="md"/><Boxbg="primary"height={100}radius="md"/><Boxbg="primary"height={100}radius="md"/><Boxbg="primary"height={100}radius="md"/><Boxbg="primary"height={100}radius="md"/></Grid>);
🔆 In addition to the props below,
<Grid>inherits all props from<Box>,omittingdisplaywhich is always"grid".
| Name | Type | Required? | Description |
|---|---|---|---|
| alignX | ResponsiveProp<'start' | 'center' | 'end' | 'stretch'> | No | Sets ajustify-items CSS property on your component. |
| alignY | ResponsiveProp<'start' | 'center' | 'end' | 'stretch'> | No | Sets aalign-items CSS property on your component. |
| cols | ResponsiveProp<number | (number | string)[]> | No | Sets agrid-template-columns CSS property on your component. |
| distributeX | ResponsiveProp<'start' | 'center' | 'end' | 'stretch' | 'around' | 'between' | 'evenly'> | No | Sets ajustify-content CSS property on your component. |
| distributeY | ResponsiveProp<'start' | 'center' | 'end' | 'stretch' | 'around' | 'between' | 'evenly'> | No | Sets aalign-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 aninline-grid rather thangrid. |
| rows | ResponsiveProp<number | (number | string)[]> | No | Sets agrid-template-rows CSS property on your component. |
typeGapProp=|keyofDashTokens["gap"]|[keyofDashTokens["gap"],keyofDashTokens["gap"]];
A layout component that can add positioning properties to itself inside ofa<Grid> component.
Check out an example onCodeSandbox
import*asReactfrom"react";import{Grid,GridItem,Box}from"@dash-ui/react-layout";constComponent=()=>(<Gridcols={3}rows={[100,100]}gap={{sm:"sm",md:"md"}}>{/* This item spans 3 columns */}<GridItembg="primary"colStart={1}colEnd={4}radius="md"/><Boxbg="primary"radius="md"/><Boxbg="primary"radius="md"/><Boxbg="primary"radius="md"/></Grid>);
🔆 In addition to the props below,
<GridItem>inherits all props from<Box>.
| Name | Type | Required? | Description |
|---|---|---|---|
| alignX | ResponsiveProp<'start' | 'center' | 'end' | 'stretch'> | No | Sets ajustify-self CSS property on your component. |
| alignY | ResponsiveProp<'start' | 'center' | 'end' | 'stretch'> | No | Sets aalign-self CSS property on your component. |
| colStart | ResponsiveProp<number | string> | No | Sets agrid-column-start CSS property on your component. |
| colEnd | ResponsiveProp<number | string> | No | Sets agrid-column-end CSS property on your component. |
| rowStart | ResponsiveProp<number | string> | No | Sets agrid-row-start CSS property on your component. |
| rowEnd | ResponsiveProp<number | string> | No | Sets agrid-row-end CSS property on your component. |
A layout component that is a container for<LayerItem>s.
Check out an example onCodeSandbox
import*asReactfrom"react";import{Layer,LayerItem}from"@dash-ui/react-layout";constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Layerwidth={600}height={600}><LayerItemplacement="bottomRight"bg="primary"size={64}radius="md"/><LayerItemplacement="topLeft"bg="primary"size={64}radius="md"/></Layer>);
🔆
<Layer>inherits all of its props from<Box>,omittingpositionwhich is always"relative".
A layout component than positions itself absolutely inside of its containerin whichever placement you decide.
Check out an example onCodeSandbox
import*asReactfrom"react";import{Layer,LayerItem}from"@dash-ui/react-layout";constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Layerwidth={400}height={400}><LayerItemplacement="bottomRight"bg="primary"size={64}radius="md"/><LayerItemplacement="topLeft"bg="primary"size={64}radius="md"/></Layer>);
🔆 In addition to the props below,
<LayerItem>inherits all props from<Box>.
| Name | Type | Required? | Description |
|---|---|---|---|
| offset | ResponsiveProp<number | string> | No | Sets amargin between the edges of the layer item's container. |
| placement | ResponsiveProp<Placements> | Yes | Sets the placement of your layer item relative to its container. SeePlacements. |
| z | ResponsiveProp<number> | No | Sets az-index CSS property on your component. |
typePlacements=|"top"|"right"|"bottom"|"left"|"center"|"topLeft"|"topRight"|"bottomRight"|"bottomLeft";
A layout component that distributes its items in a row without wrappingor shrinking.
Check out an example onCodeSandbox
import*asReactfrom"react";import{Row,Box}from"@dash-ui/react-layout";constComponent=()=>(// Responsive props are opt-in. In order to use them// you have to define a "mediaQueries" prop on your// <LayoutProvider><Rowwidth="100%"gap={{sm:"sm",md:"md"}}><Boxbg="primary"width={100}height={120}radius="md"/><Boxbg="primary"width={140}height={140}radius="md"/><Boxbg="primary"width={80}height={124}radius="md"/><Boxbg="primary"width={90}height={96}radius="md"/></Row>);
🔆 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 |
Returns theresponsivestylesused for creating responsive layout props.
// See https://github.com/dash-ui/responsiveResponsiveStyles<DashTokens,MediaQueries,DashThemeNames>
To use media query types with@dash-ui/react-layout, you have to use the module declarationpattern:
Play with this example onCodeSandbox
constmediaQueries={sm:"only screen and (min-width: 0em)",md:"only screen and (min-width: 35em)",lg:"only screen and (min-width: 80em)",}asconst;typeAppMediaQueries=typeofmediaQueries;declare module"@dash-ui/react-layout"{exportinterfaceMediaQueriesextendsAppMediaQueries{}}// OR alternativelydeclare module"@dash-ui/react-layout"{exportinterfaceMediaQueries{sm:string;md:string;lg:string;}}
To use variable types with@dash-ui/react-layout, you have to use the module declarationpattern:
Play with this example onCodeSandbox
consttokens={color:{red:"#c17",},};typeAppTokens=typeoftokens;declare module"@dash-ui/styles"{exportinterfaceDashTokensextendsAppTokens{}}// OR alternativelydeclare module"@dash-ui/styles"{exportinterfaceDashTokens{color:{red:string;};}}
MIT