B ❐ X L
A layout primitive for the styled component age.
Installation
$ npm i boxl styled-components
Built with styled components which is required as a peer dependency
Usage
Examples are written in TypeScript
Define Components
Create components with the boxl
function passing default props and styling. (All following examples use these components.)
// Base.tsx
Examples
direction: vertical
(default)
direction: horizontal
Theme Setup
First, follow Styled Components instructions on setting up a theme with TypeScript.
Once you have defined a theme, we must annotate boxl
with it using the provided Boxl<T>
interface. A common pattern is to re-export the annotated boxl
function for reuse.
import Boxl boxl as b from "boxl"import Theme from "../types/Theme" const boxl = b as Boxl<Theme>
API
boxl
boxl
is a function that returns a BoxlComponent
. There are two ways to use it:
- Use predefined element methods:
boxl.divBoxlProps
Available for all
JSX.IntrinsicElements
- Pass a component:
boxlReact.ComponentTypeBoxlProps
React.ComponentType
is any function or class component
Component Example
This allows another component to be passed for styling and is useful when you need to style a 3rd party component (e.g. react-router's <Link />
).
;;; ;
BoxlProps
These props may be passed as a default props object or to the returned component itself as JSX props.
With the exception of
css
, each prop is defined asBoxlProp<A, P, T>
.
alignHorizontal
- left | center | right
Description
Control horizontal alignment of children. If value is undefined, Child fills available Parent space.
center
Example: // AlignHorizontal.tsx
alignVertical
- top | center | bottom
Description
Aligns children vertically regardless of direction
.
bottom
Example: // AlignVertical.tsx
childGrow
- number
Description
Sets grow amount on all children equally. Useful in combination with childWrap
.
Example
childGrow={1}
causes Child components to fill available Parent space evenly if possible.
// ChildGrow.tsx
childIdealSize
- string (CSS length)
Description
Sets idealSize
on all children. Useful in combination with childWrap
.
Example
childIdealSize="150px"
causes Child components to prefer 150 pixel width if possible.
childWrap
- auto | even
Description
Allows Child components to wrap if needed.
childWrap="auto"
Example 1:
childWrap="auto"
with childGrow={1}
Example 2:
childWrap="even"
with childGrow={1}
Example 3:
css
:
- string
- CSSObject
- template literal
- function passed a tagged template literal
Description
Applies style to the component.
Example
;
direction
- vertical | horizontal
Description
Controls the direction that children flow.
"vertical"
Example 1:
"horizontal"
Example 2:
grow
- number
Description
Determines how the component expands in relation to its parent and siblings.
Example
idealSize
- string (CSS length)
Description
Defines the preferred/ideal width or hight (depending on the parent's direction
) of the component and may need to be combined with min-/max-/width via the css property to achieve the desired result.
If the parent direction is "vertical" (default), idealSize
will affect the height of the component. If the parent direction is "horizontal", idealSize
will affect the width of the component.
Example
spacing
- string (CSS length)
Description
Defines the space between children without affecting their distance from the edge of their parent.
Example
BoxlProp<A, P, T>
BoxlProp<A, P, T>
is an interface where parameter A
is a primitive value (e.g. "left" | "center" | "right"
), P
is props, and T
is theme:
; ; ;
BoxlProp
is the union of three types:
| (A | undefined)
- a primitive value (or undefined)| (BoxlPropThemeFn<A | undefined, P, T>)
- a function that receives component props and returnsBoxlProp
| (BoxlPropMediaQuery<A | undefined, P, T>)
- an object with keys corresponding to a media query string and values that areBoxlProp
Example Usage:
// alignHorizontal as A // alignHorizontal as BoxlPropThemeFn // alignHorizontal as BoxlPropMediaQuery
Develop
npm i
install project and test app depsnpm start
starts storybooknpm test:unit
runs unit testsnpm test:visual
runs visual tests (requires storybook to be running e.g.npm start
)npm test:visual:watch
runs visual tests in watch modenpm run build
compilesdist/
npm pack
generates.tgz
for local testing