react-styled-flex v2.0.0-rc.2

react-styled-flex

Simple, light, unopinionated, CSS standard compliant Flexbox component for react using styled-components

Changelog

This is react-styled-flex@2 documentation. For version 1, please follow this link. Following changes are introduced in version 2:

✂️ Breaking changes

• is prop of FlexBox and FlexItem component is longer supported. Instead use native styled-components "as" polymorphic prop to render another react component or html element.
• Supports styled-components version greater than or equal to >=5.1.0. If you want to use older versions of styled-components, please install react-styled-flex version 1 by using npm install react-styled-flex@latest-1 command.

🚀 Enhancements

• Typescript rewrite.
• ~20% lightweight than version 1.
• Supports SSR and SSG rendering.
• Introduces Box component.
• Uses styled-components shouldForwardProp mechanism to avoid leaking props to DOM. As a result, is prop from version 1 is no longer supported.

Features

• Lightweight and dependency free, ~2.4 KB minified or ~1.1 KB minified + gzipped.
• Clean underlying HTML DOM. No prop leakage to DOM.
• Supports flex-gap feature. For non supported browsers, it degrades gracefully by applying appropriate margin properties.
• Supports rendering of any react component or html element.
• Supports unitless values wherever required.
• Supports SSR and SSG rendering.
• TypeScript support.

Installation

Yarn

yarn add react-styled-flex

Npm

npm i react-styled-flex

react-styled-flex requires peer dependencies react and styled-components. You need to add them separately.

API

• react-styled-flex exports three components: Box, FlexBox and FlexItem.
• Box behaves as basic CSS box. FlexBox and FlexItem extends Box.
• FlexBox behaves as a container with display: flex rule.
• FlexItem as acts as a child for FlexBox. Though FlexBox can have other components as child as well.
• Only use FlexItem if you need to provide additional styles to child components. See Props section for more details.
• FlexItem can be treated as FlexBox for nested childs by setting box prop as true on FlexItem

Usage

react-styled-flex exports three components: Box, FlexBox and FlexItem. All renders simple div with styles derived from passed props.

import { Box, FlexBox, FlexItem } from "react-styled-flex";

const Layout = () => {
    return <FlexBox center>
        <Box padding={10}>Child 1</Box>
        <FlexItem>Child 2</FlexItem>
        <FlexItem flex={1}>Child 3</FlexItem>
    </FlexBox>
}

On rendering Layout component,

• One parent div with style display: flex; justify-content: center; align-items: center and three nested divs will be rendered.
  • First child will have padding of 10px.
  • Second child will be simple div.
  • Third child will have style flex: 1;

For rendering elements other than divs, please refer Change underlying element section.

Props

Box

All props are optional.

FlexBox

All props are optional and all boolean props defaults to false.

FlexItem

All props are optional and all boolean props defaults to false.

Supports unitless values

• react-styled-flex supports unitless values where units are required. In that case value will be auto suffixed with with px unit.
• Only values where unites are required(eg. height, width, margin) will be suffixed.
• CSS rules which don't have units won't be suffixed (eg. order)

Supports flex gap feature

• Browser supports flex gap feature

  • If flex gap feature is supported in browser than gap, columnGap and rowGap props will function as per specification.

• Browser don't support flex gap feature

  • If browser does not supports it, then we intend to provide graceful degradation of flex gap feature by setting margin. This fallback is provided only if, either of gap props is set and wrap prop is not set.
  • If wrap is set then gap wont work in non-supported browser.
  • Rest all props are supported.

Change underlying element

• By default FlexBox and FlexItem renders div in the DOM.

• We can change it to any HTML element or react component using styled-components as prop.

• Example:

  import { FlexBox, FlexItem } from "react-styled-flex";
  
  /* other logic */
  
  <FlexBox center>
      <FlexItem as={"button"}>Child 1</FlexItem>
      <FlexItem as={"button"}>Child 2</FlexItem>
  </FlexBox>

  Render Child 1 and Child 2 as button

• Similarly any react component can be rendered

License

MIT © Piyush Lodaya

Resources

• A Complete Guide to Flexbox
• CSS Flexible Box Layout