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 is a good primer.
To use layout classes import the iron-flex-layout-classes
file. You must do this in any element that uses any of the iron-flex-layout
styles.
<link rel="import" href="bower_components/iron-flex-layout/iron-flex-layout-classes.html">
Then include the module(s) that you need:
<!-- include classes in the main document --> <style is="custom-style" include="iron-flex iron-flex-alignment">
or:
<!-- import classes in an element --> <style include="iron-flex iron-flex-alignment">
Then simply apply the classes to any element.
<div class="layout horizontal wrap">
Many of the layout rules involve combinations of multiple classes (such as layout horizontal wrap
above), and will need a combination of modules. The order in which the classes are specified doesn't matter, so layout horizontal
and horizontal layout
are equivalent.
There are 5 modules available:
iron-flex
. Basic flex layouts.iron-flex-reverse
. Reverse flexbox layouts.iron-flex-alignment
. Main axis, cross axis and self alignment.iron-flex-factors
. All the available flex factors.iron-positioning
. Generic, non-flexbox positioning helpers.Example: using classes in the main document
<head> ... <link rel="import" href="bower_components/iron-flex-layout/iron-flex-layout-classes.html"> ... <!-- main document -- include the module you need in a custom-style element --> <style is="custom-style" include="iron-flex"></style> </head> <body> <div class="layout horizontal"> <div>One</div> <div>Two</div> <div>Three</div> </div> </body>
Example: using classes in a Polymer element
<link rel="import" href="bower_components/iron-flex-layout/iron-flex-layout-classes.html"> ... <dom-module id="mixin-demo"> <!-- inside an element -- include the module you need in a standard style element --> <style include="iron-flex"></style> <template> <div class="layout horizontal"> <div>One</div> <div>Two</div> <div>Three</div> </div> </template> <script> Polymer({ is: 'mixin-demo' }); </script> </dom-module>
It‘s important to note that unlike the previous layout class stylesheets (found in /classes/iron-flex-layout.html
), the new version does not use the /deep/
combinator: it does not work across local DOM boundaries, and the modules must be imported into each scope where they’re used.
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
<head> ... <link rel="import" href="bower_components/iron-flex-layout/iron-flex-layout.html"> ... <!-- main document -- apply mixins in a custom-style element --> <style is="custom-style"> .container { @apply(--layout-horizontal); @apply(--layout-wrap); } </style> </head> <body> <div class="container"> <div>One</div> <div>Two</div> <div>Three</div> </div> </body>
Example: using mixins in a Polymer element
<link rel="import" href="bower_components/iron-flex-layout/iron-flex-layout.html"> ... <dom-module id="mixin-demo"> <!-- inside an element -- apply mixins in a standard style element --> <style> .container { @apply(--layout-horizontal); @apply(--layout-wrap); } </style> <template> <div class="container"> <div>One</div> <div>Two</div> <div>Three</div> </div> </template> <script> Polymer({ is: 'mixin-demo' }); </script> </dom-module>
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 in the Polymer developer guide.
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-vertical | Vertical layout container. |
The classes listed here are included in the iron-flex
module of the iron-flex-layout-classes
file.
Example: classes
<div class="layout horizontal"> <div>One</div> <div>Two</div> <div>Three</div> </div>
Example: mixins
<style is="custom-style"> .container { @apply(--layout-horizontal); } </style> <div class="container"> <div>One</div> <div>Two</div> <div>Three</div> </div>
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. |
The classes listed here are included in the iron-flex
module of the iron-flex-layout-classes
file.
Example: classes
<div class="horizontal layout"> <div>Alpha</div> <div class="flex">Beta (flex)</div> <div>Gamma</div> </div>
Example: mixins
<style is="custom-style"> .container { @apply(--layout-horizontal); } .flexchild { @apply(--layout-flex); } </style> <div class="container"> <div>Alpha</div> <div class="flexchild">Beta (flex)</div> <div>Gamma</div> </div>
The same rules can be used for children in vertical layouts.
Example: classes
<div class="vertical layout" style="height:250px"> <div>Alpha</div> <div class="flex">Beta (flex)</div> <div>Gamma</div> </div>
Example: mixins
<style is="custom-style"> .container { @apply(--layout-vertical); } .flexchild { @apply(--layout-flex); } </style> <div class="container" style="height: 250px"> <div>One</div> <div class="flexchild">Two</div> <div>Three</div> </div>
Note: for vertical layouts, the container needs to have a height for the children to flex correctly.
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.
The classes listed here are included in the iron-flex-factors
module of the iron-flex-layout-classes
file.
Example: classes
<div class="horizontal layout demo"> <div class="flex-3">Alpha</div> <div class="flex">Beta</div> <div class="flex-2">Gamma</div> </div>
Example: mixins
<style is="custom-style"> .container { @apply(--layout-horizontal); } .flexchild { @apply(--layout-flex) } .flex2child { @apply(--layout-flex-2); } .flex3child { @apply(--layout-flex-3); } </style> <div class="container"> <div class="flex3child">One</div> <div class="flexchild">Two</div> <div class="flex2child">Three</div> </div>
By default, children stretch to fit the cross-axis (e.g. vertical stretching in a horizontal layout).
<div class="horizontal layout" style="height: 154px"> <div>Stretch Fill</div> </div>
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
<div class="horizontal layout center" style="height: 154px"> <div>Center</div> </div>
Example: mixins, cross-axis center
<style is="custom-style"> .container { @apply(--layout-horizontal); @apply(--layout-center); } </style> <div class="container" style="height: 154px"> <div>Center</div> </div>
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
<div class="horizontal layout start" style="height: 154px"> <div>start</div> </div>
Example: mixins, cross-axis start
<style is="custom-style"> .container { @apply(--layout-horizontal); @apply(--layout-start); } </style> <div class="container" style="height: 154px"> <div>start</div> </div>
Example: classes, cross-axis end
<div class="horizontal layout end" style="height: 154px"> <div>end</div> </div>
Example: mixins, cross-axis end
<style is="custom-style"> .container { @apply(--layout-horizontal); @apply(--layout-end); } </style> <div class="container" style="height: 154px"> <div>end</div> </div>
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. |
The classes listed here are included in the iron-flex-alignment
module of the iron-flex-layout-classes
file.
Example: classes, start justified
<div class="horizontal start-justified layout"> <div>start-justified</div> </div>
Example: mixins, center justified
<style is="custom-style"> .container { @apply(--layout-horizontal); @apply(--layout-center-justified); } </style> <div class="container"> <div>center-justified</div> </div>
Example: classes, end justified
<div class="horizontal end-justified layout"> <div>end-justified</div> </div>
Example: mixins, equal space between elements
<style is="custom-style"> .container { @apply(--layout-horizontal); @apply(--layout-justified); } </style> <div class="container"> <div>justified</div> <div>justified</div> <div>justified</div> </div>
Example: classes, equal space around each element
<div class="horizontal around-justified layout"> <div>around-justified</div> <div>around-justified</div> </div>
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 | --layout-self-stretch | Stretches the child to fit the cross-axis. |
Example: classes
<div class="horizontal layout" style="height: 120px;"> <div class="flex self-start">Alpha</div> <div class="flex self-center">Beta</div> <div class="flex self-end">Gamma</div> <div class="flex self-stretch">Delta</div> </div>
Example: mixins
<style is="custom-style"> .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); } </style> <div class="container"> <div class="child1">Alpha</div> <div class="child2">Beta</div> <div class="child3">Gamma</div> <div class="child4">Delta</div> </div>
Note: The flex class (and --layout-flex mixin) shown in these examples is added for the demo and not required for self-alignment.
Wrapped layouts can be enabled with the wrap
class or --layout-wrap
mixin.
Example: classes
<div class="horizontal layout wrap" style="width: 220px"> <div>Alpha</div> <div>Beta</div> <div>Gamma</div> <div>Delta</div> </div>
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 vertical-reverse | --layout-vertical-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). |
The classes listed here are included in the iron-flex-reverse
module of the iron-flex-layout-classes
file.
Example: mixins
<style is="custom-style"> .container { @apply(--layout-horizontal-reverse); } </style> <div class="container"> <div>Alpha</div> <div>Beta</div> <div>Gamma</div> <div>Delta</div> </div>
It‘s common to want the entire <body>
to fit to the viewport. By themselves, Polymer’s layout features on <body>
don't achieve the result. You can make <body>
take up the entire viewport by adding the fullbleed
class:
<body class="fullbleed vertical layout"> <div class="flex">Fitting a fullbleed body.</div> </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; }
This class is included in the iron-positioning
module of the iron-flex-layout-classes
file.
Note that the fullbleed
class only works on the <body>
tag. This is the only rule in the stylesheet that is scoped to a particular tag.
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”). |
The classes listed here are included in the iron-positioning
module of the iron-flex-layout-classes
file.
Note:When using
fit
layout, the element must have an ancestor with fixed size andposition: relative
layout to fit inside of.
Example: classes
<div class="demo">Before <span>[A Span]</span> After</div> <div class="demo">Before <span class="block">[A Block Span]</span> After</div> <div class="demo">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>