opencollective/atomic-layout

Physical representation of layout composition to create declarative responsive layouts in React.

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, without caring
// what components are rendered inside.
const areasMobile = `
  thumbnail
  header
  footer
`

// Responsive areas? Built-in!
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 is responsive by default. It uses Bootstrap 4 breakpoints, but you can define custom breakpoints to match your requirements.

Motivation

Think of how we create layouts today. Most likely we define a set of reusable units (atoms) to combine them into functional compositions. But how do we handle spacing that should describe the position of our units? Usually, we manage CSS properties of those units to make sure the spacing is just right. Not only that results into writing redundant CSS, but it also makes our atoms contextual and, thus, non-maintainable.

Atomic layout solves this problem by exposing a dedicated layer responsible for spacial distribution in a layout, or any of its parts. That allows to reuse atom components in any layout possible without mutating them.

Install

npm install atomic-layout

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

Documentation

See the Official documentation.

Here 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

Browser support

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, and browse through the issues labeled help wanted or good first issue. Those are a good place to start. Feature suggestions or bug reports, discussion, and pull requests are always welcome!