atomic-layout

Atomic Layout

Atomic Layout is a spatial distribution library for React. It uses CSS Grid to define layout areas and render them as React components. This pattern encourages separation of elements and spacing, preventing contextual implementations and boosting maintenance of layouts.

import React from 'react'
import { Composition } from 'atomic-layout'

// Define layout areas: visual representation
// of what composes a layout, detached from
// what components are actually rendered.
const areasMobile = `
  thumbnail
  header
  footer
`

// Declare responsive changes of your areas.
// Operate in two dimensions, remove areas
// or introduce new ones.
const areasTablet = `
  thumbnail header
  thumbnail footer
`

const Card = ({ title, imageUrl, actions }) => (
  <Composition areas={areasMobile} areasMd={areasTablet} gap={20}>
    {/* Get React components based on provided areas */}
    {({ Thumbnail, Header, Footer }) => (
      <React.Fragment>
        <Thumbnail>
          {/* Render anything, including another Composition */}
          <img src={imageUrl} alt={title} />
        </Thumbnail>
        {/* Preserve semantics with polymorphic prop */}
        <Header as="h3">{title}</Header>
        {/* Responsive props: just suffix with a breakpoint name */}
        <Footer padding={10} paddingMd={20}>
          {actions}
        </Footer>
      </React.Fragment>
    )}
  </Composition>
)

export default Card

Atomic Layout comes with built-in responsive support. It uses Bootstrap 4 breakpoints by default, which you can always override with the custom breakpoints to match your requirements.

Motivation

Modern layout development is about modularity and composition. Following the best practices of Atomic design, we strive toward independent UI units that gradually compose into more meaningful pieces. While the attention paid to units implementation is thorough, we often overlook how to achieve layout composition that scales. It's as if we forget that spacing defines composition.

When it comes to distributing the spacing things get more difficult. First of all, true contextless spacing is hard. To make things worse, all present solutions couple spacing with UI elements, inevitably making small resusable pieces contextful and, thus, hard to maintain.

Atomic Layout helps you to compose your elements by introducing a dedicated spacing layer called Composition. It encourages you to separate concerns between UI elements' visual appearance and spacing between them. With the first-class responsive support at your disposal you can build gorgeous responsive permutations of your elements without leaving the dedicated spacing layer, keeping UI elements contextless and predictable. Embrace the era of a true layout composition!

Install

npm install atomic-layout

Make sure to have React (16.0+) and styled-components (4.0+) installed.

Documentation

See the Official documentation.

There are some shortcuts to get you started:

• Motivation
• Getting started
• Responsive props
• Recipes

Examples

• Flats list (https://codesandbox.io/s/5wwp76310n)

Materials

	Creating layouts that last (React Finland, 2019) Find out the main aspects of a layout's maintainability and why spacing plays a crucial role in it. Learn how to wield layout composition as an actual React component–a missing glue for your elements and design systems. Live demo
	Layout composition as a React component (SurviveJS) Read through the extensive interview about how Atomic layout came to be, how it's different from other solutions, and which practices it encourages.
	The Future of Layouts (React Vienna, 2018) Watch Artem discussing the biggest obstacle to achieve maintainable layouts, and showcases a way to combine existing technologies to build clean UI implementations using Atomic layout. Live demo Slides

Community

• Spectrum
• Reactiflux

Browser support

Atomic Layout's browser support is made by the browser support of underlying technologies the library uses. Pay attention if your project can support CSS Grid to be sure you can use Atomic Layout.

See the Support table for CSS Grid. For Internet Explorer support please read this issue.

Contributing

Thank you for deciding to contribute! Your involvement makes a significant impact on the library and its future.

Please read the Contribution guidelines to get familiar with the contributing process. The issues labeled help wanted or good first issue are a good place to start cooperating on Atomic Layout. Feature suggestions or bug reports, discussion, and pull requests are always welcome!