react-aerial v0.1.3

aerial

Aerial is a customizable flexbox based mobile-first responsive library for React DOM & React Native.

DEMO

install

npm install react-aerial --save

dom example

import React from "react";

import { ScreenDetailsProvider, Container, Row, Col } from "react-aerial";

const App = ( ) => (
  <ScreenDetailsProvider>
    <Container>
      <Row xsHorizontalGutter={8} xsVerticalGutter={16}>
        <Col xs={1} sm={1/2} md={1/3} lg={2/5}>
          Donec congue porttitor diam, eu fermentum nisl laoreet ac.
        </Col>
        <Col xs={1} sm={1/2} md={1/3} lg={1/5}>
          Sed tincidunt faucibus massa, ut commodo magna sodales suscipit.
        </Col>
        <Col xs={1} sm={1} md={1/3} lg={2/5}>
          Vivamus nec enim eu diam mollis luctus.
        </Col>
      </Row>
    </Container>
  </ScreenDetailsProvider>
);

export default App;

react native example

import React from "react";
import { Text } from 'react-native';

import { ScreenDetailsProvider, Container, Row, Col } from "react-aerial/react-native";

const App = ( ) => (
  <ScreenDetailsProvider>
    <Container>
      <Row xsHorizontalGutter={8} xsVerticalGutter={16}>
        <Col xs={1} sm={1/2} md={1/3} lg={2/5}>
          <Text>Donec congue porttitor diam, eu fermentum nisl laoreet ac.</Text>
        </Col>
        <Col xs={1} sm={1/2} md={1/3} lg={1/5}>
          <Text>Sed tincidunt faucibus massa, ut commodo magna sodales suscipit.</Text>
        </Col>
        <Col xs={1} sm={1} md={1/3} lg={2/5}>
          <Text>Vivamus nec enim eu diam mollis luctus.</Text>
        </Col>
      </Row>
    </Container>
  </ScreenDetailsProvider>
);

export default App;

pros

• Flexible col & offset widths (e.g. 1/2, 1/5) instead of fixed row partition (e.g. 12, 60)
• Customizable breakpoints without recompiling the library
• Rendering order, gutters & alignment of the cols can be defined related to screen size
• Unified component structure for react dom and react native

cons

• The current implementation does not use stylesheets to give more flexibility, and support react native. It uses the style property of the elements instead, which can decrease the rendering performance.
• The library does not use media queries either. To eliminte the need of them, it relies on the screen width of the client platform that it gets from window, or Dimensions, and subscribes to their changes. Because of this, it can't be used for server side rendering.

Components

<Container />

Provides a wrapper that is aligned to the middle of the screen. The width of the container for each device size must be defined at the breakpoints.

props

<Row />

A flexbox based wrapper for Cols, that will wrap them to the new line on overflow. Only Col components should be provided as children to this component. Applies gutter as padding on Cols, and reorder them based on their their {size}Order prop. Row uses negative margins on the top and sides to compensate the gutters.

props

<Col />

Smallest unit of the responsive grid. The width of cols can be set on different device sizes relative to the width of the Row, as well as their horizontal alignment and order can be changed. Should be used as the children of Row component.

props

<Show />

Conditionally renders children based on the provided props and the matching device size.

props

example

import React from "react";

import { ScreenDetailsProvider, Show } from "react-aerial";

const App = ( ) => (
  <ScreenDetailsProvider>
    <Show xs={false} md={true}>
      Only visible on md and above
    </Show>
  </ScreenDetailsProvider>
);

export default App;

<Switch />

Renders the highest matching react component or element.

props

example

import React from "react";

import { ScreenDetailsProvider, Switch } from "react-aerial";

const DesktopComponent = ({ title }) => (
  <div>
    <h1>{title}</h1>
    <div>Rendered on large devices</div>
  </div>
);

const App = ( ) => (
  <ScreenDetailsProvider>
    <Switch
      xs={<div>Rendered on small devices</div>}
      md={DesktopComponent}
      title="Passed prop"
    />
  </ScreenDetailsProvider>
);

export default App;

<ScreenDetailsProvider />

Broadcasts screenDetails in the wrapped subtree to other aerial components. For using Aerial it is necesarry to wrap the component tree into a ScreenDetailsProvider component.

props

The default breakpoints are the following:

[
  { size: "xs", minWidth: 0,    containerWidth: "100%" },
  { size: "sm", minWidth: 768,  containerWidth: 750    },
  { size: "md", minWidth: 992,  containerWidth: 970    },
  { size: "lg", minWidth: 1200, containerWidth: 1170   }
]

example

import React from "react";

import { ScreenDetailsProvider, Container, Row, Col } from "react-aerial";

const breakpoints = [
  { size: "small", minWidth: 0, containerWidth: "100%" },
  { size: "large", minWidth: 992, containerWidth: 970 }
];

const App = ( ) => (
  <ScreenDetailsProvider breakpoints={breakpoints}>
    <Container>
      <Row
        smallVerticalGutter={8}
        largeVerticalGutter={16}
        largeHorizontalGutter={16}
      >
        <Col small={1} large={1}>
          Donec congue porttitor diam, eu fermentum nisl laoreet ac.
        </Col>
        <Col small={1} large={1/3}>
          Sed tincidunt faucibus massa, ut commodo magna sodales suscipit.
        </Col>
        <Col small={1} large={1/3} largeOffset={1/3}>
          Vivamus nec enim eu diam mollis luctus.
        </Col>
      </Row>
    </Container>
  </ScreenDetailsProvider>
);

export default App;

Higher order components

withScreenDetails(Component)

Adds the screenDetails object as prop to the wrapped component, and rerenders it on change of screenDetails.

example

import React from "react";
import classNames from "classnames";

import { ScreenDetailsProvider, withScreenDetails } from "react-aerial";

const Component = ({ screenDetails }) => (
  <div className={classNames({
      "component--small": screenDetails.breakpoints[0].active,
      "component--large": screenDetails.breakpoints[2].active
    })}
  >
    Conditional classes applied
  </div>
);

const ComponentWithScreenDetails = withScreenDetails(Component);

const App = ( ) => (
  <ScreenDetailsProvider>
    <ComponentWithScreenDetails />
  </ScreenDetailsProvider>
);

export default App;

screenDetails object

properties

License

MIT License

Copyright (c) 2017 László Kardinál

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.