react-boxl

B ❐ X L

Layout primitives for the styled component age.

Installation

$ npm i react-boxl styled-components

Built with styled components which is required as a peer dependency

Usage

Create components with the boxl function passing default props and styling.

// Examples.tsx
import * as React from "react";
import { boxl } from "boxl";

const Container = boxl({
  spacing: "16px", // ⬅︎ adds spacing between children
  style: `
    border: 8px solid black;
    box-shadow: 12px -12px 0 0 black;
    margin: 12px 12px 0 0;
    padding: 24px;
  `,
});

/**
 * Additional props may be statically defined 
 * using an optional type parameter.
 */

interface SectionProps {
  primary?: boolean;
}

const Section = boxl<SectionProps>({
  style: styled => styled` // ⬅︎ tagged template literal à la styled-components
    ${props => (props.primary ? `background: black;` : ``)};
    border: 8px solid black;
    padding: 32px;
  `,
});

Direction Vertical (default)

const Vertical = () => (
  <Container>
    <Section primary={true} />
    <Section />
    <Section />
  </Container>
);

Direction Horizontal

const Horizontal = () => (
  <Container direction="horizontal">
    <Section grow={1} primary={true} />
    <Section />
    <Section />
  </Container>
);

API

Box

childGrow?: number

Sets grow on all children. Useful in combination with childWrap.

Example:

<Box childGrow={1}>
  <Box>1</Box> // grow: 1
  <Box>2</Box> // grow: 1
</Box>

childIdealWidth?: string (CSS length)

Sets idealWith on all children. Useful in combination with childWrap.

Example:

<Box childIdealWidth="20%">
  <Box>1</Box> // idealWidth: 20%
  <Box>2</Box> // idealWidth: 20%
</Box>

childWrap?: "auto" | "even"

Allows children to wrap when available space is exceeded

• "auto": children to wrap naturally
• "even": children that wrap maintain any set idealWidth or childIdealWidth which is useful for achieving an even grid layout

Example:

// Children wrap naturally
<Box 
  childGrow={1}
  childWrap="auto"
  direction="horizontal" 
>
  <Box>1</Box>
  <Box>2</Box>
  <Box>3</Box>
  <Box>4</Box>
</Box>

// Children wrap evenly (orphans maintain idealWidth)
<Box 
  childGrow={1}
  childIdealWidth="200px"
  childWrap="even"
  direction="horizontal" 
>
  <Box>1</Box>
  <Box>2</Box>
  <Box>3</Box>
  <Box>4</Box>
</Box>

direction?: "horizontal" | "vertical"

Direction children will flow—stacked or side-by-side. (default "vertical")

Example:

  // Children are stacked
  <Box direction="vertical">
    <Box>1</Box>
    <Box>2</Box>
    <Box>3</Box>
    <Box>4</Box>
  </Box>

  // Children are side-by-side
  <Box direction="horizontal">
    <Box>1</Box>
    <Box>2</Box>
    <Box>3</Box>
    <Box>4</Box>
  </Box>

element?: string (HTML element—"a", "h1", etc.)

HTML element to be rendered (default "div")

Example:

  // Anchor element will be rendered
  <Box element="a" href="http://google.com">
    Take me to google...
  </Box>

grow?: number

Amount that Box should grow in relation to available space or siblings (default: 0)

Example:

  <Parent>
    <Box grow={1}>1</Box> // fills available space
    <Box>2</Box>
    <Box>3</Box>
  </Parent>

horizontalAlign?: "left" | "center" | "right"

Aligns children horizontally regardless of direction (default: "left")

idealWidth?: string (CSS length)

Optimal width considering content size and available space (i.e. flex-basis) (default: "left")

Note: Use alongside width or max/min-width styles

padding?: string (CSS length)

Adds padding and takes priority over padding set via style

spacing?: string (CSS length)

Defines gap between children

style?: string | template literal | (style) => style`tagged template literal`

Defines styling via plain string, template literal, or tagged template literal function. The last option allows interpolation of props including a theme if a styled-components theme provider is present.

Note: See styled components docs for more info

Example:

  // string
  <Box style="background: red; color: white;" />
  
  // template literal
  <Box 
    style={`
      background: red; 
      color: white;
    `} 
  />
  
  // tagged template literal function
  <Box 
    style={style => style`
      background: ${props => props.theme.color.primary}; 
      color: white;
    `}
  />

verticalAlign?: "top" | "center" | "bottom"

Aligns children vertically regardless of direction (default: "top")

Develop

• npm i install project and test app deps
• npm start starts storybook
• npm test:unit runs unit tests
• npm test:visual runs visual tests (requires storybook to be running e.g. npm start)
• npm test:visual:watch runs visual tests in watch mode
• npm run build compiles dist/
• npm pack generates .tgz for local testing