diff --git a/docs/app/partials/layout-children.tmpl.html b/docs/app/partials/layout-children.tmpl.html
new file mode 100644
index 00000000000..15400b0c843
--- /dev/null
+++ b/docs/app/partials/layout-children.tmpl.html
@@ -0,0 +1,322 @@
+
+
+
Children within a Layout Container
+
+
+ To customize the size and position of elements in a layout container, use the
+ flex
, flex-order
, and flex-offset
attributes on the container's child elements:
+
+
+
+
+
+
+ [flex="20"]
+
+
+ [flex="70"]
+
+
+ [flex]
+
+
+
+
+
+
+ Add the flex
directive to a layout's child element and the element will flex (grow or shrink) to fit
+ the area unused by other elements. flex
defines how the element will ajust its size with respect to its
+ parent container and the other elements within the container.
+
+
+
+
+
+
+ [flex="30"]
+
+
+ [flex="45"]
+
+
+ [flex="25"]
+
+
+ [flex="33"]
+
+
+ [flex="66"]
+
+
+ [flex="50"]
+
+
+ [flex]
+
+
+
+
+
+
+
+ A layout child's flex
directrive can be given an integer value from 0-100.
+ The element will stretch to the percentage of available space matching the value. Currently, the flex
+ directive value is restricted to multiples of five, 33 or 66.
+
+
+
For example: flex="5", flex="20", flex="33", flex="50", flex="66", flex="75", ... flex="100"
.
+
+
+
+
+
+ flex 33% on mobile,
and 66% on gt-sm devices.
+
+
+ flex 66% on mobile,
and 33% on gt-sm devices.
+
+
+
+
+
+
+
+ See the layout options page for more information on responsive flex directives like
+ hide-sm
and layout-wrap
used in the above examples.
+
+
+
+
+
+
+
Additional Flex Values
+
+
+ There are additional flex values provided by Angular Material to improve flexibility and to make the API
+ easier to understand.
+
+
+
+
+
+
+ [flex="0"]
+
+
+ [flex="none"]
+
+
+ [flex]
+
+
+ [flex="grow"]
+
+
+ [flex="auto"]
+
+
+ [flex="auto"]
+
+
+ [flex="initial"]
+
+
+
+
+
+
+
+
+ flex |
+ Will grow and shrink as needed. Starts with a size of 0%. Same as flex="0" . |
+
+
+ flex="none" |
+ Will not grow or shrink. Sized based on it's width and height values. |
+
+
+ flex="initial" |
+ Will shrink as needed. Starts with a size based on it's width and height values. |
+
+
+ flex="auto" |
+ Will grow and shrink as needed. Starts with a size based on it's width and height values. |
+
+
+ flex="grow" |
+ Will grow and shrink as needed. Starts with a size of 100%. Same as flex="100" . |
+
+
+
+
+
+
+
+
+
Ordering HTML Elements
+
+
+ Add the flex-order
directive to a layout child to set its
+ order position within the layout container. Any integer value from -20 to 20 is accepted.
+
+
+
+
+
+
+
+
[flex-order="1"]
+
[flex-order-gt-md="3"]
+
+
+
+
[flex-order="3"]
+
[flex-order-gt-md="1"]
+
+
+
+
+
+
+
+
+ API |
+ Device width when breakpoint overrides default |
+
+
+
+ flex-order |
+ Sets default layout order unless overridden by another breakpoint. |
+
+
+ flex-order-xs |
+ width < 600px |
+
+
+ flex-order-gt-xs |
+ width >= 600px |
+
+
+ flex-order-sm |
+ 600px <= width < 960px |
+
+
+ flex-order-gt-sm |
+ width >= 960px |
+
+
+ flex-order-md |
+ 960px <= width < 1280px |
+
+
+ flex-order-gt-md |
+ width >= 1280px |
+
+
+ flex-order-lg |
+ 1280px <= width < 1920px |
+
+
+ flex-order-gt-lg |
+ width >= 1920px |
+
+
+ flex-order-xl |
+ width >= 1920px |
+
+
+
+
+
+ See the layout options page for more information on directives like
+ hide
, hide-gt-md
, and show-gt-md
used in the above examples.
+
+
+
+
+
+
+
Add Offsets to the Preceding HTML Elements
+
+
+ Add the flex-offset
directive to a layout child to set its
+ offset percentage within the layout container. Values must be multiples
+ of 5
or 33
/ 66
. These offsets establish a margin-left
+ with respect to the preceding element or the containers left boundary.
+
+
+
+ When using flex-offset
the margin-left offset is applied... regardless of your choice of flex-order
.
+ or if you use a flex-direction: reverse
.
+
+
+
+
+
+
+ [flex-offset="15"]
+ [flex="66"]
+
+
+ [flex]
+
+
+
+
+
+
+
+
+ API |
+ Device width when breakpoint overrides default |
+
+
+
+ flex-offset |
+ Sets default margin-left offset (%-based) unless overridden by another breakpoint. |
+
+
+ flex-offset-xs |
+ width < 600px |
+
+
+ flex-offset-gt-xs |
+ width >= 600px |
+
+
+ flex-offset-sm |
+ 600px <= width < 960px |
+
+
+ flex-offset-gt-sm |
+ width >= 960px |
+
+
+ flex-offset-md |
+ 960px <= width < 1280px |
+
+
+ flex-offset-gt-md |
+ width >= 1280px |
+
+
+ flex-offset-lg |
+ 1280px <= width < 1920px |
+
+
+ flex-offset-gt-lg |
+ width >= 1920px |
+
+
+ flex-offset-xl |
+ width >= 1920px |
+
+
+
+
+
+
diff --git a/docs/app/partials/layout-container.tmpl.html b/docs/app/partials/layout-container.tmpl.html
index 2552b5218d4..3a2f35b9f4e 100644
--- a/docs/app/partials/layout-container.tmpl.html
+++ b/docs/app/partials/layout-container.tmpl.html
@@ -1,28 +1,11 @@
-
Overview
-
- Angular Material's responsive CSS layout is built on
- flexbox.
-
+
Layout and Containers
- The layout system is based upon element attributes rather than CSS classes.
- Attributes provide an easy way to set a value (eg. layout="row"
) and
- help us separate concerns: attributes define layout, and classes define styling.
-
-
-
- Note: Due to performance problems related to attribute selectors in IE11, our attributes are converted
- to class selectors at runtime. You should continue to use layout attribute selectors in your code.
-
-
-
-
Layout Attribute
-
- Use the layout
attribute on an element to arrange its children
+ Use the layout
directive on a container element to specify the layout direction for its children:
horizontally in a row (layout="row"
) or vertically in a column (layout="column"
).
- Row layout is the default if you specify the layout
attribute without a value.
+ Note that row
is the default layout direction if you specify the layout
directive without a value.
@@ -36,7 +19,9 @@ Layout Attribute
-
+
+
+
First item in row
@@ -50,6 +35,111 @@
Layout Attribute
- See the layout options page for information on responsive layouts and other options.
+ Note that layout
only affects the flow direction for that container's immediate children.
+
+
+
+
+
+
Layouts and Responsive Breakpoints
+
+
+ As discussed in the Layout Introduction page you can
+ make your layout change depending upon the device view size by using breakpoint alias suffixes.
+
+
+
+ To make your layout automatically change depending upon the device screen size, use one to the following layout
+ APIs to set the layout direction for devices with view widths:
-
+
+
+
+
+ API |
+ Device width when breakpoint overrides default |
+
+
+
+ layout |
+ Sets default layout direction unless overridden by another breakpoint. |
+
+
+ layout-xs |
+ width < 600px |
+
+
+ layout-gt-xs |
+ width >= 600px |
+
+
+ layout-sm |
+ 600px <= width < 960px |
+
+
+ layout-gt-sm |
+ width >= 960px |
+
+
+ layout-md |
+ 960px <= width < 1280px |
+
+
+ layout-gt-md |
+ width >= 1280px |
+
+
+ layout-lg |
+ 1280px <= width < 1920px |
+
+
+ layout-gt-lg |
+ width >= 1920px |
+
+
+ layout-xl |
+ width >= 1920px |
+
+
+
+
+
+
+
+
+
+
+ For the demo below, as you shrink your browser window width notice the flow direction changes to column
+ for mobile devices (xs
). And as you expand it will reset to row
+ for gt-sm
view sizes.
+
+
+
+
+
+
+
+ I'm above on mobile, and to the left on larger devices.
+
+
+ I'm below on mobile, and to the right on larger devices.
+
+
+
+
+
+
+
+
+ See the Layout Options page for more options such as padding, alignments, etc.
+
+
+
+
+
+
diff --git a/docs/app/partials/layout-grid.tmpl.html b/docs/app/partials/layout-grid.tmpl.html
deleted file mode 100644
index 04e921be4c6..00000000000
--- a/docs/app/partials/layout-grid.tmpl.html
+++ /dev/null
@@ -1,232 +0,0 @@
-
-
-
- To customize the size and position of elements in a layout, use the
- flex
, flex-order
, and flex-offset
attributes.
-
-
-
-
-
-
- [flex]
-
-
- [flex]
-
-
- [flex]
-
-
-
-
-
- Add the flex
attribute to a layout's child element and the element will flex (grow or shrink) to fit
- the area unused by other elements. flex
defines how the element will ajust its size with respect to its
- parent container and the other other elements within the container.
-
-
-
-
-
-
- [flex="30"]
-
-
- [flex="45"]
-
-
- [flex="25"]
-
-
- [flex="33"]
-
-
- [flex="66"]
-
-
- [flex="50"]
-
-
- [flex]
-
-
-
-
-
-
- A layout child's flex
attribute can be given an integer value from 0-100.
- The element will stretch to the percentage of available space matching the value.
-
- Currently, the flex
attribute value is restricted to multiples of five and 33 or 66.
-
- For example: flex="5", flex="20", flex="33", flex="50", flex="66", flex="75", ... flex="100"
.
-
-
- See the layout options page for more information on responsive flex attributes like
- hide-sm
and layout-wrap
used in the above examples.
-
-
-
-
-
-
- [flex="0"]
-
-
- [flex="none"]
-
-
- [flex]
-
-
- [flex="grow"]
-
-
- [flex="auto"]
-
-
- [flex="auto"]
-
-
- [flex="initial"]
-
-
-
-
-
-
- There are additional flex values provided by Angular Material to improve flexibility and to make the API
- easier to understand.
-
-
-
- flex |
- Will grow and shrink as needed. Starts with a size of 0%. Same as flex="0" . |
-
-
- flex="none" |
- Will not grow or shrink. Sized based on it's width and height values. |
-
-
- flex="initial" |
- Will shrink as needed. Starts with a size based on it's width and height values. |
-
-
- flex="auto" |
- Will grow and shrink as needed. Starts with a size based on it's width and height values. |
-
-
- flex="grow" |
- Will grow and shrink as needed. Starts with a size of 100%. Same as flex="100" . |
-
-
-
-
-
-
-
-
-
[flex-order="1"]
-
[flex-order-gt-md="3"]
-
-
-
-
[flex-order="3"]
-
[flex-order-gt-md="1"]
-
-
-
-
-
- Add the flex-order
attribute to a layout child to set its
- position within the layout. Any value from -9 to 9 is accepted.
-
-
-
- flex-order |
- Sets element order. |
-
-
- flex-order-sm |
- Sets element order on devices less than 600px wide. |
-
-
- flex-order-gt-sm |
- Sets element order on devices greater than 600px wide. |
-
-
- flex-order-md |
- Sets element order on devices between 600px and 960px wide. |
-
-
- flex-order-gt-md |
- Sets element order on devices greater than 960px wide.
- |
-
- flex-order-lg |
- Sets element order on devices between 960px and 1200px wide. |
-
-
- flex-order-gt-lg |
- Sets element order on devices greater than 1200px wide. |
-
-
-
- See the layout options page for more information on attributes like
- hide
, hide-gt-md
, and show-gt-md
used in the above examples.
-
-
-
-
-
-
- [flex offset="33"]
-
-
- [flex]
-
-
-
-
-
- Add the flex-offset
attribute to a layout child to set its
- offset percentage within the layout. Values must be multiples
- of 5
or 33
/ 66
.
-
-
-
- flex-offset |
- Sets element offset. |
-
-
- flex-offset-sm |
- Sets element offset on devices less than 600px wide. |
-
-
- flex-offset-gt-sm |
- Sets element offset on devices greater than 600px wide. |
-
-
- flex-offset-md |
- Sets element offset on devices between 600px and 960px wide. |
-
-
- flex-offset-gt-md |
- Sets element offset on devices greater than 960px wide.
- |
-
- flex-offset-lg |
- Sets element offset on devices between 960px and 1200px wide. |
-
-
- flex-offset-gt-lg |
- Sets element offset on devices greater than 1200px wide. |
-
-
-
-
diff --git a/docs/app/partials/layout-introduction.tmpl.html b/docs/app/partials/layout-introduction.tmpl.html
new file mode 100644
index 00000000000..34c02df1bcf
--- /dev/null
+++ b/docs/app/partials/layout-introduction.tmpl.html
@@ -0,0 +1,373 @@
+
+
+
Overview
+
+ Angular Material's Layout features provide sugar to enable developers to more easily create modern,
+ responsive layouts on top of CSS3 flexbox.
+ The layout API consists of a set of Angular directives that can
+ be applied to any of your application's HTML content.
+
+
+
+
+ Using HTML Directives as the API provides an easy way to set a value (eg. layout="row"
) and
+ helps with separation of concerns: Attributes define layout while CSS classes assign styling.
+
+
+
+
+
+
+ HTML Markup API |
+ Allowed values (raw or interpolated) |
+
+
+
+
+ layout |
+ row | column |
+
+
+ flex |
+ integer (increments of 5 for 0%->100%) |
+
+
+ flex-order |
+ integer values from -20 to 20 |
+
+
+ flex-offset |
+ integer (increments of 5 for 0%->100%, 100%/3, 200%/3) |
+
+
+ layout-align |
+ start|center|end|space-around|space-between start|center|end|stretch |
+
+
+ layout-fill |
+ |
+
+
+ layout-wrap |
+ |
+
+
+ layout-nowrap |
+ |
+
+
+ layout-margin |
+ |
+
+
+ layout-padding |
+ |
+
+
+ show |
+ |
+
+
+ hide |
+ |
+
+
+
+
+
+
And if we use Breakpoints as specified in Material Design:
+
+
+
+
+
We can associate breakpoints with mediaQuery definitions using breakpoint alias(es):
+
+
+
+
+ Breakpoint |
+ MediaQuery (pixel range) |
+
+
+
+
+ xs |
+ '(max-width: 599px)' |
+
+
+ gt-xs |
+ '(min-width: 600px)' |
+
+
+ sm |
+ '(min-width: 600px) and (max-width: 959px)' |
+
+
+ gt-sm |
+ '(min-width: 960px)' |
+
+
+ md |
+ '(min-width: 960px) and (max-width: 1279px)' |
+
+
+ gt-md |
+ '(min-width: 1280px)' |
+
+
+ lg |
+ '(min-width: 1280px) and (max-width: 1919px)' |
+
+
+ gt-lg |
+ '(min-width: 1920px)' |
+
+
+ xl |
+ '(min-width: 1920px)' |
+
+
+
+
+
+
+
+ API with Responsive Breakpoints
+
+
+
Now we can combine the breakpoint alias
with the Layout API to easily support Responsive breakpoints
+ with our simple Layout markup convention. The alias
is simply used as suffix extensions to the Layout
+ API keyword.
+
e.g.
+
+
+
+ This notation results in, for example, the following table for the layout
and flex
APIs:
+
+
+
+
+
+ layout API |
+ flex API |
+ Activates when device |
+
+
+
+ layout |
+ flex |
+ Sets default layout direction & flex unless overridden by another breakpoint. |
+
+
+ layout-xs |
+ flex-xs |
+ width < 600px |
+
+
+ layout-gt-xs |
+ flex-gt-xs |
+ width >= 600px |
+
+
+ layout-sm |
+ flex-sm |
+ 600px <= width < 960px |
+
+
+ layout-gt-sm |
+ flex-gt-sm |
+ width >= 960px |
+
+
+ layout-md |
+ flex-md |
+ 960px <= width < 1280px |
+
+
+ layout-gt-md |
+ flex-gt-md |
+ width >= 1280px |
+
+
+ layout-lg |
+ flex-lg |
+ 1280px <= width < 1920px |
+
+
+ layout-gt-lg |
+ flex-gt-lg |
+ width >= 1920/b>px |
+
+
+ layout-xl |
+ flex-xl |
+ width >= 1920px |
+
+
+
+
Below is an example usage of the Responsive Layout API:
+
+
+
+
+
+
+
+
+ This Layout API means it is much easier to set up and maintain flexbox layouts vs. defining everything via CSS.
+ The developer uses the Layout HTML API to specify intention and the Layout engine handles all the issues of CSS flexbox styling.
+
+
+
+ The Layout engine will log console warnings when it encounters conflicts or known issues.
+
+
+
+
+
+
+
+
Under-the-Hood
+
+
+ Due to performance problems when using Attribute Selectors with Internet Explore browsers; see the following for more details:
+
+
+
+
+
+ Layout directives dynamically generate class selectors at runtime. And the Layout CSS classNames and styles have each been
+ predefined in the angular-material.css
stylesheet.
+
+
+
+ Developers should continue to use Layout directives in the HTML
+ markup as the classes may change between releases.
+
+
+
+ Let's see how this directive-to-className transformation works. Consider the simply use of the layout
and flex
directives (API):
+
+
+
+
+
+
+
+
First item in row
+
Second item in row
+
+
+
+
+
First item in column
+
Second item in column
+
+
+
+
+
+
+
+
+ At runtime, these attributes are transformed to CSS classes.
+
+
+
+
+
+
+
+
First item in row
+
Second item in row
+
+
+
+
+
First item in column
+
Second item in column
+
+
+
+
+
+
+
+ Using the style classes above defined in angular-material.css
+
+
+
+
+ .flex {
+ -webkit-flex: 1 1 0%;
+ -ms-flex: 1 1 0%;
+ flex: 1 1 0%;
+ box-sizing: border-box;
+ }
+ .flex-20 {
+ -webkit-flex: 1 1 20%;
+ -ms-flex: 1 1 20%;
+ flex: 1 1 20%;
+ max-width: 20%;
+ max-height: 100%;
+ box-sizing: border-box;
+ }
+
+ .layout-row .flex-33 {
+ -webkit-flex: 1 1 33%;
+ -ms-flex: 1 1 33%;
+ flex: 1 1 33%;
+ box-sizing: border-box;
+ }
+
+ .layout-row .flex-66 {
+ -webkit-flex: 1 1 66%;
+ -ms-flex: 1 1 66%;
+ flex: 1 1 66%;
+ box-sizing: border-box;
+ }
+
+
+ .layout-row .flex-33 {
+ max-width: calc(100% / 3);
+ max-height: 100%;
+ }
+
+ .layout-row .flex-66 {
+ max-width: calc(200% / 3);
+ max-height: 100%;
+ }
+
+ .layout-column .flex-33 {
+ max-width: 100%;
+ max-height: calc(100% / 3);
+ }
+
+ .layout-column .flex-66 {
+ max-width: 100%;
+ max-height: calc(200% / 3);
+ }
+
+
+
diff --git a/docs/app/partials/layout-options.tmpl.html b/docs/app/partials/layout-options.tmpl.html
index 6af5cda68cd..954d75f13d5 100644
--- a/docs/app/partials/layout-options.tmpl.html
+++ b/docs/app/partials/layout-options.tmpl.html
@@ -15,45 +15,69 @@
See the Container Elements page for a basic explanation
- of layout attributes.
+ of layout directives.
To make your layout change depending upon the device screen size, there are
- other layout
attributes available:
+ other layout
directives available:
+
+
+ API |
+ Activates when device |
+
+
layout |
- Sets the default layout on all devices. |
+ Sets default layout direction unless overridden by another breakpoint. |
+
+
+ layout-xs |
+ width < 600px |
+
+
+ layout-gt-xs |
+ width >= 600px |
layout-sm |
- Sets the layout on devices less than 600px wide (phones). |
+ 600px <= width < 960px |
layout-gt-sm |
- Sets the layout on devices greater than 600px wide (bigger than phones). |
+ width >= 960px |
layout-md |
- Sets the layout on devices between 600px and 960px wide (tablets in portrait). |
+ 960px <= width < 1280px |
layout-gt-md |
- Sets the layout on devices greater than 960px wide (bigger than tablets in portrait). |
+ width >= 1280px |
layout-lg |
- Sets the layout on devices between 960 and 1200px wide (tablets in landscape). |
+ 1280px <= width < 1920px |
layout-gt-lg |
- Sets the layout on devices greater than 1200px wide (computers and large screens). |
+ width >= 1920px |
+
+
+ layout-xl |
+ width >= 1920px |
+
+
+
+
Layout Margin, Padding, Wrap and Fill
+
+
@@ -73,16 +97,17 @@
- layout-margin
adds margin around each flex
child. It also adds a margin to the layout container itself.
+ layout-margin
adds margin around each flex
child. It also adds a margin to the layout
+ container itself.
- layout-padding
adds padding inside each flex
child. It also adds padding to the layout container itself.
+ layout-padding
adds padding inside each flex
child. It also adds padding to the layout
+ container itself.
layout-fill
forces the layout element to fill its parent container.
-
-
+
Here is a non-trivial group of flex
elements using layout-wrap
@@ -97,77 +122,38 @@