react-boxl v0.12.0

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: `
    background: white;
    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;` : ``)};
    background: white;
    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

Example:

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

Example:

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

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

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>

Example:

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

Example:

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

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

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

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