Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@material/layout-grid
Advanced tools
@material/layout-grid - npm Package Compare versions
Comparing version 0.1.2 to 0.2.0
| { | ||
| "name": "@material/layout-grid", | ||
| "version": "0.1.2", | ||
| "version": "0.2.0", | ||
| "description": "The Material Components for the web layout grid component", | ||
@@ -5,0 +5,0 @@ "license": "Apache-2.0", |
143
README.md
@@ -51,5 +51,3 @@ <!--docs: | ||
| Margins (the space between the edge of the grid and the edge of the first cell) and gutters (the space between edges of | ||
| adjacent cells) are user-definable, with the Material Design spec recommending 8px, 16px, 24px or 40px as the sizes to | ||
| choose from. The default margin and gutter are both 16px, but they don't have to be the same size. | ||
| Margins (the space between the edge of the grid and the edge of the first cell) and gutters (the space between edges of adjacent cells) can be customized on different devices respectively based on design needs. Layout grids set default margins and gutters to 24px on desktop, 16px on tablet and phone, according to the Material Design spec. | ||
@@ -63,32 +61,37 @@ The grid and cells are not styled in any way, serving only for alignment and positioning of elements. | ||
| <div class="mdc-layout-grid"> | ||
| <div class="mdc-layout-grid__cell"></div> | ||
| <div class="mdc-layout-grid__cell"></div> | ||
| <div class="mdc-layout-grid__cell"></div> | ||
| <div class="mdc-layout-grid__inner"> | ||
| <div class="mdc-layout-grid__cell"></div> | ||
| <div class="mdc-layout-grid__cell"></div> | ||
| <div class="mdc-layout-grid__cell"></div> | ||
| </div> | ||
| </div> | ||
| ``` | ||
| The grid should have the `mdc-layout-grid` class, and every cell should have the `mdc-layout-grid__cell` class. | ||
| Behavior for grids containing direct children without the `mdc-layout-grid__cell` class is undefined. | ||
| The grid should have the `mdc-layout-grid` class. Every cell should have the `mdc-layout-grid__cell` class and must be wrapped by `mdc-layout-grid__inner` for proper alignment. Behavior for grids containing direct children without the `mdc-layout-grid__cell` class is undefined. | ||
| ### Margins and gutters | ||
| The default size for both the margins and gutters in MDC layout grid is 16px. | ||
| Layout grids set default margins and gutters to 24px on desktop, 16px on tablet and phone. | ||
| You can change the margins and gutters for a grid using the `--mdc-layout-grid-margin` and `--mdc-layout-grid-gutter` | ||
| custom properties, respectively. This requires support for CSS custom properties on the end-user's browser. | ||
| The Material Design spec recommends 8px, 16px, 24px or 40px as the sizes to choose from, we set those as choices in our demo catalog. However, MDC layout grid doesn't impose any restrictions. | ||
| The Material Design spec recommends 8px, 16px, 24px or 40px as the sizes to choose from, but MDC layout grid doesn't | ||
| impose any restrictions. | ||
| #### CSS custom properties | ||
| You can change the margins and gutters for a grid using the `--mdc-layout-grid-margin-#{$device}` and `--mdc-layout-grid-gutter-#{$device}` custom properties, respectively. This requires support for CSS custom properties on the end-user's browser. | ||
| ```css | ||
| .my-grid { | ||
| --mdc-layout-grid-margin: 40px; | ||
| --mdc-layout-grid-gutter: 16px; | ||
| --mdc-layout-grid-margin-desktop: 40px; | ||
| --mdc-layout-grid-gutter-tablet: 16px; | ||
| --mdc-layout-grid-gutter-phone: 8px; | ||
| } | ||
| ``` | ||
| > Note: Due to the implementation of MDC layout grid, it's not possible to use a margin smaller than half of the size | ||
| of the gutter, in most browsers. As support for [CSS Grid](https://www.w3.org/TR/css-grid-1/) lands in browsers, this | ||
| limitation will go away, as MDC layout grid is progressively enhanced to support it. | ||
| #### Sass variables | ||
| You can change the margins and gutters using sass variables if you are compiling from them. MDC layout grid uses sass map `mdc-layout-grid-default-margin` and `mdc-layout-grid-default-gutter` to define margins and gutters on different screen types. | ||
| ### Column spans | ||
@@ -98,17 +101,17 @@ | ||
| <div class="mdc-layout-grid"> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-6"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-4"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-2"></div> | ||
| <div class="mdc-layout-grid__inner"> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-6"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-4"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-2"></div> | ||
| </div> | ||
| </div> | ||
| ``` | ||
| Cells have a default span size of 4 columns, with other sizes being possible by applying one of the span classes, of the | ||
| form `mdc-layout-grid__cell--span-{columns}`, where `{columns}` is an integer between 1 and 12. | ||
| You can set the cells span by applying one of the span classes, of the form `mdc-layout-grid__cell--span-{columns}`, where `{columns}` is an integer between 1 and 12. If the chosen span size is larger than the available number of columns at the current screen size, the cell behaves as if its chosen span size were equal to the available number of columns at that screen size. That is, it takes up the entirety of its row, and no more than that. | ||
| If the chosen span size is larger than the available number of columns at the current screen size, the cell behaves as | ||
| if its chosen span size were equal to the available number of columns at that screen size. That is, it takes up the | ||
| entirety of its row, and no more than that. | ||
| If the span classes are not set, `mdc-layout-grid__cell` will fallback to a default span size of 4 columns. You can make it a different number by changing the default value. However, this number needs to be provided at compile time by using sass variable `$mdc-layout-grid-default-column-span`. | ||
| ### Column spans for specific screen sizes | ||
| #### Column spans for specific screen sizes | ||
| It's possible to tweak the behavior of cells further by defining different column spans for specific screen sizes. | ||
@@ -122,5 +125,7 @@ These override the default at that size. | ||
| <div class="mdc-layout-grid"> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-6 mdc-layout-grid__cell--span-8-tablet"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-4 mdc-layout-grid__cell--span-6-tablet"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-2 mdc-layout-grid__cell--span-4-phone"></div> | ||
| <div class="mdc-layout-grid__inner"> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-6 mdc-layout-grid__cell--span-8-tablet"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-4 mdc-layout-grid__cell--span-6-tablet"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--span-2 mdc-layout-grid__cell--span-4-phone"></div> | ||
| </div> | ||
| </div> | ||
@@ -133,2 +138,32 @@ ``` | ||
| ### Max width | ||
| MDC layout grids take up the parent element space by default. However, user can set `$mdc-layout-grid-max-width` to restrict the max-width of the layout grid. | ||
| ### Nested grid | ||
| When your contents need extra structure that cannot be supported by single layout grid, you can nest layout grid within each other. To nest layout grid, add a new `mdc-layout-grid__inner` to wrap around nested `mdc-layout-grid__cell` within an existing `mdc-layout-grid__cell`. | ||
| The nested layout grid behaves exactly like when they are not nested, e.g, they have 12 columns on desktop, 8 columns on tablet and 4 columns on phone. They also use the **same gutter size** as their parents, but margins are not re-introduced since they are living within another cell. | ||
| However, Material guideline do not recommend have a deeply nested grid since it might means a over complicated UX. | ||
| ```html | ||
| <div class="mdc-layout-grid"> | ||
| <div class="mdc-layout-grid__inner"> | ||
| <div class="mdc-layout-grid__cell"> | ||
| <div class="mdc-layout-grid__inner"> | ||
| <div class="mdc-layout-grid__cell"><span>Second level</span></div> | ||
| <div class="mdc-layout-grid__cell"><span>Second level</span></div> | ||
| </div> | ||
| </div> | ||
| <div class="mdc-layout-grid__cell">First level</div> | ||
| <div class="mdc-layout-grid__cell">First level</div> | ||
| </div> | ||
| </div> | ||
| ``` | ||
| ### Reordering | ||
@@ -141,5 +176,7 @@ | ||
| <div class="mdc-layout-grid"> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--order-3"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--order-1"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--order-2"></div> | ||
| <div class="mdc-layout-grid__inner"> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--order-3"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--order-1"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--order-2"></div> | ||
| </div> | ||
| </div> | ||
@@ -151,2 +188,3 @@ ``` | ||
| ### Alignment | ||
@@ -160,5 +198,7 @@ | ||
| <div class="mdc-layout-grid"> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--align-top"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--align-middle"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--align-bottom"></div> | ||
| <div class="mdc-layout-grid__inner"> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--align-top"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--align-middle"></div> | ||
| <div class="mdc-layout-grid__cell mdc-layout-grid__cell--align-bottom"></div> | ||
| </div> | ||
| </div> | ||
@@ -173,23 +213,36 @@ ``` | ||
| ```scss | ||
| @include mdc-layout-grid(16px, 16px, 1600px); | ||
| @include mdc-layout-grid(desktop, 16px, 1600px); | ||
| ``` | ||
| `mdc-layout-grid` defines a grid and should be applied to the container element. The mixin takes three parameters: | ||
| - `$size`: the target platform: `desktop`, `tablet` or `phone`. | ||
| - `$margin`: the size of the grid margin. | ||
| - `$gutter`: the size of the gutter between cells. | ||
| - `$max-width` (optional): the maximum width of the grid, at which point space stops being distributed by the columns. | ||
| Note that the margin and gutter can be overriden at runtime by using the CSS custom properties detailed in the | ||
| "Margins and gutters" section under "CSS class usage". | ||
| ### mdc-layout-grid-inner | ||
| ```scss | ||
| @include mdc-layout-grid-inner(desktop, 16px, 16px); | ||
| ``` | ||
| `mdc-layout-grid-inner` defines wrapper of the grid cells. The mixin takes three parameters: | ||
| - `$size`: the target platform: `desktop`, `tablet` or `phone`. | ||
| - `$margin`: the size of the grid margin. | ||
| - `$gutter`: the size of the gutter between cells. | ||
| ### mdc-layout-grid-cell | ||
| ```scss | ||
| @include mdc-layout-grid-cell(16px, 4); | ||
| @include mdc-layout-grid-cell(desktop, 4, 16px); | ||
| ``` | ||
| `mdc-layout-grid-cell` defines a cell and should be applied to the cell element. The mixin takes two parameters: | ||
| `mdc-layout-grid-cell` defines a cell and should be applied to the cell element. The mixin takes three parameters: | ||
| - `$size`: the target platform: `desktop`, `tablet` or `phone`. | ||
| - `$default-span` (optional, default 4): how many columns this cell should span (1 to 12). | ||
| - `$gutter`: the size of the gutter between cells. Be sure to use the same value as for the parent grid. | ||
| - `$span` (optional, default 4): how many columns this cell should span (1 to 12). | ||
| > Note even though size is passed in as one of the arguments, it won't apply any `media-query` rules. It is set for using the correct CSS custom properties to overriden the margin and gutter at runtime (See [Margins and gutters](#margins-and-gutters) section for detail). | ||
| ### mdc-layout-grid-cell-order | ||
@@ -202,3 +255,3 @@ | ||
| `mdl-layout-grid-cell-order` reorders a cell inside a grid. It's an optional mixin that should be applied to the cell | ||
| `mdc-layout-grid-cell-order` reorders a cell inside a grid. It's an optional mixin that should be applied to the cell | ||
| element, together with the mandatory `mdc-layout-grid-cell`. | ||
@@ -215,5 +268,5 @@ | ||
| `mdl-layout-grid-cell-align` aligns a cell vertically inside a grid. It's an optional mixin that should be applied to | ||
| `mdc-layout-grid-cell-align` aligns a cell vertically inside a grid. It's an optional mixin that should be applied to | ||
| the cell element, together with the mandatory `mdc-layout-grid-cell`. | ||
| It takes a single parameter, `$position`, which expects `top`, `middle` or `bottom` as values. |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
New author
Supply chain riskA new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
New author
Supply chain riskA new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by14.82%
58863
- Lines of code
- increased by17.51%
463
- Number of lines in readme file
- increased by25.36%
262
No dependency changes