flex-layout.md 20 KB

Edit Raw Blame History



title: Flexbox layout with iron-flex-layout
summary: "Simple flexbox layout"
tags: ['beginner']
elements: ['iron-flex-layout']
updated: 2015-05-03

.demo {
  background-color: #ccc;
  padding: 4px;
  margin: 12px;
}

.demo div {
  background-color: white;
  padding: 12px;
  margin: 4px;
}

.tall {
  height: 124px;
}

.demo.vertical {
  height: 250px;
}

demo-tabs::shadow #results {
  width: 40%;
  max-width: initial;
}

table {
  margin: 16px 20px;
}
td,th {
  padding 0px 8px;
}

Overview
The iron-flex-layout component provides simple ways to use CSS flexible box layout, also known as flexbox. This component provides two different ways to use flexbox:


Layout classes. The layout class stylesheet provides a simple set of class-based flexbox rules. Layout classes
let you specify layout properties directly in markup.
Custom CSS mixins.  The mixin stylesheet includes custom CSS mixins that can be applied 
inside a CSS rule using the @apply function. 


Using the classes or CSS mixins is largely a matter of preference. The following sections discuss 
how to use the each of the stylesheets.

 Note: Before using either of these stylesheets, it's helpful to be familiar with the basics 
of flexbox layout. Chris Coyier's [A Complete Guide to Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) is a 
good primer. 

### Using layout classes

To use layout classes import the `classes/iron-flex-layout` file.

    
Then simply apply the classes to any element.

    
Many of the layout rules involve combinations of multiple classes (such as `layout horizontal wrap` above).
The order in which the classes are specified doesn't matter, so `layout horizontal` and `horizontal layout`
are equivalent.

_Currently_, the layout class stylesheet uses the `/deep/` combinator 
and therefore, works across all local DOM boundaries. 

Because `/deep/` is slated to be removed from the shadow DOM spec, this
stylesheet will eventually be replaced by a  set of rules that do not use
`/deep/`. When that happens, the stylesheet will need to be imported into each
scope  where it's used.

### Using layout mixins

Custom mixins can be applied inside a Polymer 
custom element's stylesheet, **or** inside a `custom-style` stylesheet to apply styles to the 
main document. (They cannot be applied in the main document without a `custom-style` stylesheet.)

**Example: using mixins in the main document**

    
      ...

      
      ...

      
        .container {
          @apply(--layout-horizontal);
          @apply(--layout-wrap);
        }
      

        One
        Two
        Three
      

**Example: using mixins in a Polymer element**

    
      ...

    
        .container {
          @apply(--layout-horizontal);
          @apply(--layout-wrap);
        }
      

          One
          Two
          Three
        
      
In general the mixins require a little more code to use, but they can be preferable if you
don't want to use the classes, or if you want to switch layouts based on a media query.

Custom CSS properties and mixins are features provided by the Polymer library. 
See [Cross-scope styling](https://www.polymer-project.org/1.0/docs/devguide/styling.html#xscope-styling) 
in the Polymer developer guide.

## Horizontal and vertical layout

Create a flex container that lays out its children vertically or horizontally.

Class | Mixin | Result 
:-|:-|:-
layout horizontal| ‑‑layout-horizontal | Horizontal layout container.
layout vertical | ‑‑layout-verical | Vertical layout container.

**Example: classes** 

    
      One
      Two
      Three
    

**Example: mixins** 

    
        .container {
          @apply(--layout-horizontal);
        }
      

          One
          Two
          Three
        

        ...

**Example output**


  One
  Two
  Three


### Flexible children

Children of a flex container can use flex to control their own sizing.

Class | Mixin | Result 
:-|:-|:-
flex| ‑‑layout-flex | Expand the child to fill available space in the main axis.
flex-ratio| ‑‑layout-flex-ratio | Assign a flex ratio of 1 to 12.
flex-none| ‑‑layout-flex-none | Don't flex the child.
flex-auto| ‑‑layout-flex-auto | Sets flex `flex-basis` to `auto` and `flex-grow` and `flex-shrink` to 1.


**Example: classes** 

        
          Alpha
          Beta (flex)
          Gamma
        

**Example: mixins** 

    
        .container {
          @apply(--layout-horizontal);
        }
        .flexchild {
          @apply(--layout-flex);
        }
      

          One
          Two
          Three
        

        ...

**Example output**


  Alpha
  Beta (flex)
  Gamma


#### Flexible children in vertical layouts

The same rules can be used for children in vertical layouts.

**Example: classes**

    
      Alpha
      Beta (flex)
      Gamma
    

**Example: mixins**

    
        .container {
          @apply(--layout-vertical);
        }
        .flexchild {
          @apply(--layout-flex);
        }
      

          One
          Two
          Three
        

        ...

**Example output**


  Alpha
  Beta (flex)
  Gamma


**Note**: for vertical layouts, the container needs to have a height for the 
children to flex correctly.

#### Flex ratios

Children elements can be told to take up more space by including a "flex ratio"
from 1 to 12. This is equivalent to specifying the CSS `flex-grow` property.

For example, the following examples make "Gamma" 2x larger than "Beta" and "Alpha" 3x larger, use 
`flex-2` and `flex-3`, respectively.

**Example: classes**

        
          Alpha
          Beta
          Gamma
        

**Example: mixins**

    
        .container {
          @apply(--layout-horizontal);
        }
        .flexchild {
          @apply(--layout-flex);
        }
        .flex2child {
          @apply(--layout-flex-2);
        }
        .flex3child {
          @apply(--layout-flex-3);
        }
      

          One
          Two
          Three
        

        ...

**Example output**


  Alpha
  Beta
  Gamma


### Cross-axis alignment

By default, children stretch to fit the cross-axis (e.g. _vertical_ stretching in a _horizontal_ layout).

    
      Stretch Fill
    

  Stretch Fill


Center _across_ the main axis (e.g. _vertical_ centering elements in a _horizontal_ layout)
by adding the `center` class or applying the `--layout-center` mixin.

**Example: classes, cross-axis center**

    
      Center
    

**Example: mixins, cross-axis center**

    
        .container {
          @apply(--layout-horizontal);
          @apply(--layout-center);
        }
      

          Center
        

        ...

**Example output, cross-axis center**


  Center


You can also position at the top/bottom (or left/right in `vertical` layouts) using the `start` or `end`
classes, or by applying the `--layout-start` or `--layout-end` mixins.


**Example: classes, cross-axis start**

    
      start
    

**Example: mixins, cross-axis start**

    
        .container {
          @apply(--layout-horizontal);
          @apply(--layout-start);
        }
      

          start
        

        ...

**Example output, cross-axis start**


  start


**Example: classes, cross-axis end**

    
      end
    

**Example: mixins, cross-axis end**

    
        .container {
          @apply(--layout-horizontal);
          @apply(--layout-end);
        }
      

          end
        

        ...

**Example output, cross-axis end**


  end


### Justification

Justifying aligns contents along the **main axis**.  Justify the layout 
by specifying  one of the following.


Class | Mixin | Result 
:-|:-|:-
`start-justified`| ‑‑layout-start-justified | Aligns contents at the start of the main axis.
`center-justified` | ‑‑layout-center-justified | Centers contents along the main axis.
`end-justified` | ‑‑layout-end-justified | Aligns contents to the end of the main axis.
`justified` | ‑‑layout-justified | Aligns contents with equal spaces between children. 
`around-justified` | ‑‑layout-around-justified | Aligns contents with equal spaces arround children. 


**Example: classes, start justified** 

    
      start-justified
    

**Example output, start justified**


  start-justified


**Example: mixins, center justified**

    
        .container {
          @apply(--layout-horizontal);
          @apply(--layout-center-justified);
        }
      

          center-justified
        

        ...

**Example output, center justified**


  center-justified


**Example: classes, end justified** 

    
      end-justified
    

**Example output, end justified**


  end-justified


**Example: mixins, equal space between elements**

    
        .container {
          @apply(--layout-horizontal);
          @apply(--layout-justified);
        }
      

          justified
          justified
          justified
        

        ...

**Example output, equal space between elements**        


  justified
  justified
  justified


**Example: classes, equal space around each element**

    
      around-justified
      around-justified
    

  around-justified
  around-justified


## Self alignment

Alignment can also be set per-child (instead of using the layout container's rules).

Class | Mixin | Result 
:-|:-|:-
`self-start`| ‑‑layout-self-start | Aligns the child at the start of the cross-axis.
`self-center` | ‑‑layout-self-center | Centers the child along the cross-axis.
`self-end` | ‑‑layout-self-end | Aligns the child at the end of the cross-axis.
`self-stretch` | ‑‑self-stretch | Stretches the child to fit the cross-axis. 

**Example: classes**

    
      Alpha
      Beta
      Gamma
      Delta
    

**Example: mixins**

    
        .container {
          @apply(--layout-horizontal);
          @apply(--layout-justified);
          height: 120px;
        }
        .container div {
          @apply(--layout-flex);
        }
        .child1 {
          @apply(--layout-self-start);
        }
        .child2 {
          @apply(--layout-self-center);
        }
        .child3 {
          @apply(--layout-self-end);
        }
        .child4 {
          @apply(--layout-self-stretch);
        }
      

          Alpha
          Beta
          Gamma
          Delta
        

        ...

**Example output**


  Alpha
  Beta
  Gamma
  Delta


 Note: The flex class 
(and --layout-flex mixin) shown in these examples is
added for the demo and not required for self-alignment. 


## Wrapping

Wrapped layouts can be enabled with the `wrap` class or `--layout-wrap` mixin.

**Example: classes**

    
      Alpha
      Beta
      Gamma
      Delta
    

**Example output**


  Alpha
  Beta
  Gamma
  Delta


## Reversed layouts

Layout direction can be mirrored using the following rules:

Class | Mixin | Result 
:-|:-|:-
layout horizontal‑reverse| ‑‑layout-horizontal-reverse | Horizontal layout with children laid out in reverse order (last-to-first).
layout verical‑reverse | ‑‑layout-verical-reverse | Vertical layout with children laid out in reverse order.
layout wrap‑reverse | ‑‑layout-wrap-reverse | Wrap layout with wrapped rows placed in the reverse order (for example, in a vertical layout, the second row is placed above the first row, instead of below).

**Example: mixins**

    
        .container {
          @apply(--layout-horizontal-reverse);
        }
      

          Alpha
          Beta
          Gamma
          Delta
        

        ...

**Example output**


  Alpha
  Beta
  Gamma
  Delta


## Full bleed <body>

It's common to want the entire `` to fit to the viewport. By themselves, Polymer's layout features on 
`` don't achieve the result. You can make `` take up the entire viewport by adding the `fullbleed` class:

    
      Fitting a fullbleed body.
    

This removes its margins and maximizes its height to the viewport. There is no equivalent mixin, but the same result can
be achieved in CSS very simply:

    body {
      margin: 0;
      height: 100vh;
    }

Note that the `fullbleed` class **only works on the `` tag.** This is the only rule in the 
stylesheet that is scoped to a particular tag.


## General purpose rules

Polymer also includes other general purpose rules for basic positioning:

Class | Mixin | Result 
:-|:-|:-
`block`| `--layout-block` | Assigns `display: block`
`invisible` | `--layout-invisible` | Assigns `visibility: hidden`
`relative` | `--layout-relative` | Assigns `position: relative`
`fit` | `--layout-fit` | Sets `position: absolute` and sets `top:0;right:0;bottom:0;left:0;` (aka "trbl fitting"). 

 Note:When using `fit` layout, the element must have an ancestor with fixed size and `position: relative` layout
to fit inside of.
 

Example: classes
<div>Before <span>[A Span]</span> After</div>

<div>Before <span class="block">[A Block Span]</span> After</div>
<div>Before invisible span <span class="invisible">Not displayed</span> After invisible span</div>
<div class="relative" style="height: 100px;">
  <div class="fit" style="background-color: #000;color: white">Fit</div>
</div>


Example output

Before [A Span] After

Before [A Block Span] After

Before invisible span Not displayed After invisible span


  Fit