Summary
- Wrapper. For containers always use the class
.container-fluid. - Nesting. Columns are immediate children of rows and content is always placed within columns.
- Sub grids. Start a sub grid with a
.rowinside the column. - Paddings. Columns just have paddings to the left and to the right. To build a grid with equal paddings to all sides use
.wui-gridand.wui-grid__item. - Minimum requirement. We optimize for all screen sizes. However, our focus is on ensuring that all content is displayed properly up to a screen size of at least 1200px.
Content with widgets
The relation between content and widgets is .col-md-8 to .col-md-4. On small devices the widgets go beneath the content.
Content
.col-md-8Widget
.col-md-4Widget
.col-md-4<div class="row">
<div class="col-md-8">
<div class="wui-bs-panel">
<div class="panel-heading">
<h2 class="panel-title">Content</h2>
</div>
<div class="panel-body">
<code>.col-md-8</code>
</div>
</div>
</div>
<div class="col-md-4">
<div class="wui-bs-panel">
<div class="panel-heading">
<h2 class="panel-title">Widget</h2>
</div>
<div class="panel-body">
<code>.col-md-4</code>
</div>
</div>
<div class="wui-bs-panel">
<div class="panel-heading">
<h2 class="panel-title">Widget</h2>
</div>
<div class="panel-body">
<code>.col-md-4</code>
</div>
</div>
</div>
</div>
Content with filters
The relation between filters and content is .col-lg-3 .col-md-4 to .col-lg-9 .col-md-8.
On small devices the filters are pushed beneath the content. Therefore we use the Bootstrap classes .push and .pull. To make sure that the grid items and the facets are on the same height, there is a .wui-grid .p-0 in each column. We use the .p-0 here to make sure that the only padding within the grid is coming from the .wui-grid-items.
With Bootstrap 5 the
.pushand.pullclasses are deprecated. We use.order- classes (e.g.,.order-1.order-md-2) for controlling the visual order of the content.
Card 1
Card 2
Card 3
Card 4
Facet 1
Facet 2
<div class="row">
<div class="col-lg-9 col-md-8 col-lg-push-3 col-md-push-4 order-1 order-md-2">
<div class="row">
<div class="wui-grid wui-grid--md p-0">
<div class="wui-grid__item col-xlg-3 col-lg-4 col-sm-6">
<div class="wui-card2">
<div class="wui-card2__body">
<h2 class="wui-card2__title">
Card 1
</h2>
</div>
</div>
</div>
<div class="wui-grid__item col-xlg-3 col-lg-4 col-sm-6">
<div class="wui-card2">
<div class="wui-card2__body">
<h2 class="wui-card2__title">
Card 2
</h2>
</div>
</div>
</div>
<div class="wui-grid__item col-xlg-3 col-lg-4 col-sm-6">
<div class="wui-card2">
<div class="wui-card2__body">
<h2 class="wui-card2__title">
Card 3
</h2>
</div>
</div>
</div>
<div class="wui-grid__item col-xlg-3 col-lg-4 col-sm-6">
<div class="wui-card2">
<div class="wui-card2__body">
<h2 class="wui-card2__title">
Card 4
</h2>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="col-lg-3 col-md-4 col-lg-pull-9 col-md-pull-8 order-2 order-md-1">
<div class="row">
<div class="wui-grid wui-grid--sm p-0 p-l-5">
<div class="wui-grid__item">
<div class="wui-facet wui-bs-panel m-0">
<div class="panel-heading">
<h2 class="panel-title">Facet 1</h2>
</div>
<div class="panel-body">
</div>
</div>
</div>
<div class="wui-grid__item">
<div class="wui-facet wui-bs-panel m-0">
<div class="panel-heading">
<h2 class="panel-title">Facet 2</h2>
</div>
<div class="panel-body">
</div>
</div>
</div>
</div>
</div>
</div>
</div>
wui-grid
The .wui-grid__item has the same padding on all sides, unlike columns which only have padding on the right and left. The width of the .wui-grid__item can be set by classes analogous to the Bootstrap cols.
There are 3 modifiers that can be used to control the padding between elements.
.wui-grid--md= 30px gap.wui-grid--sm= 20px gap.wui-grid--xs= 10px gap.wui-grid--zero= 0px gap
To ensure an equal padding around an item, the parent element of the
.wui-gridmust not have any padding. With one exception: If the parent is.wui-scene-body- don't change the padding.
Breakpoints
We are using 5 breakpoints: small, medium, large and extra large. Because the breakpoints are based on minimum width media queries, each of them applies to that specific breakpoint and all those above (e.g., .col-lg-4 applies to large and extra large devices, but not to small or medium ones)
| Range | Screen-size | Prefix |
|---|---|---|
| > 0 px | Extra small | .col-* |
| > 767 px | Small | .col-sm-* |
| > 991 px | Medium | .col-md-* |
| > 1199 px | Large | .col-lg-* |
| > 1823 px | Extra large | .col-xlg-* |
import {
WuiContainer,
WuiRow,
WuiCol,
WuiGrid,
WuiGridItem,
} from "@wui/wui-vue/lib/layout";
Description
Use the powerful mobile-first grid (via the
<wui-container>,<wui-row>,<wui-form-row>and<wui-col>components) to build layouts of all shapes and sizes thanks to a twelve column system, five default responsive tiers, CSS Sass variables and mixins, and dozens of predefined classes.
How it works
WUI's grid system uses a series of containers, rows, and columns to layout and align content. It's fully responsive. Below is an example and an in-depth look at how the grid comes together.
<wui-container class="wv-example-row">
<wui-row>
<wui-col>1 of 3</wui-col>
<wui-col>2 of 3</wui-col>
<wui-col>3 of 3</wui-col>
</wui-row>
</wui-container>
<!-- wui-grid-how-it-works.vue -->
The above example creates three equal-width columns on small, medium, large, and extra large devices using WUI's predefined grid classes. Those columns are centered in the page with the parent .container.
Breaking it down, here's how it works:
- Containers provide a means to center and horizontally pad your site's contents. Use
<wui-container>for a responsive pixel width or<wui-container fluid>formax-width: 1800pxacross all viewport and device sizes or<wui-container fluid="unlimited">forwidth: 100%across all viewport and device sizes. - Rows are wrappers for columns. Each column has horizontal
padding(called a gutter) for controlling the space between them. Thispaddingis then counteracted on the rows with negative margins. This way, all the content in your columns is visually aligned down the left side. - In a grid layout, content must be placed within columns and only columns may be immediate children of rows.
- Column prop
colsindicates the number of columns you'd like to use out of the possible 12 per row regardless of breakpoint (starting at breakpointxs). So, if you want three equal-width columns at any breakpoint, you can use<wui-col cols="4">. - Column props
sm,md,lg,xlindicate the number of columns you'd like to use out of the possible 12 per row, at the various breakpoints. So, if you want three equal-width columns at breakpointsm, you can use<wui-col sm="4">. the special valueautocan be used to take up the remaining available column space in a row. - Column
widths are set in percentages, so they're always fluid and sized relative to their parent element. - Columns have horizontal
paddingto create the gutters between individual columns, however, you can remove themarginfrom<wui-row>andpaddingfrom<wui-col>by setting theno-guttersprop on<wui-row>. - To make the grid responsive, there are five grid breakpoints, one for each responsive breakpoint: all breakpoints (extra small), small, medium, large, and extra large.
- Grid breakpoints are based on minimum width media queries, meaning they apply to that one breakpoint and all those above it (e.g.,
<wui-col sm="4">applies to small, medium, large, and extra large devices, but not the firstxsbreakpoint). - You can use predefined grid classes or Sass mixins for more semantic markup.
Containers <wui-container>
Containers (<wui-container>) are the most basic layout element in WUI. Choose from a responsive, fixed-width container (meaning its max-width changes at each breakpoint) by default, or fluid-width (meaning it's 100% wide all the time) by setting 'fluid' prop, or fluid="unlimited" prop where the container is always fluid without a breakpoint limit.
While containers can be nested, most layouts do not require a nested container.
Default container
The default <wui-container> is a responsive, fixed-width container, meaning its max-width changes at each viewport width breakpoint.
<wui-container>
<!-- Content here -->
</wui-container>
Fluid width container
Using the fluid prop on <wui-container> will render a container that is 1800px max-width, regardless of viewport breakpoint.
<wui-container fluid>
<!-- Content here -->
</wui-container>
Using the fluid="unlimited" prop will render a container that is always 100% width, regardless of viewport breakpoint.
<wui-container fluid="unlimited">
<!-- Content here -->
</wui-container>
Refer to the Grid options section table below for the default container width values.
Rows <wui-row> and <wui-form-row>
Rows are wrappers for columns. Each column has horizontal padding (called a gutter) for controlling the space between them. This padding is then counteracted on the rows with negative margins. This way, all the content in your columns is visually aligned down the left side.
You can remove the margin from <wui-row> and padding from <wui-col> by setting the no-gutters prop on <wui-row>.
Or, for compact margins (smaller gutters between columns), use the <wui-form-row> component, which is typically used when laying out forms.
Columns <wui-col>
<wui-col> Must be placed inside a <wui-row> component, or an element (such as a <div>) that has the class row applied to it, or - in the case of forms - inside a <wui-form-row> component (to obtain columns with more compact margins).
Grid options
See how aspects of the WUI grid system work across multiple devices with a handy table.
<div class="table-responsive-sm">
<table class="table table-bordered table-striped">
<thead>
<tr>
<th></th>
<th>
<strong>Extra small</strong> (xs)<br />
<code><768px</code>
</th>
<th>
<strong>Small</strong> (sm)<br />
<code>≥768px</code>
</th>
<th>
<strong>Medium</strong> (md)<br />
<code>≥992px</code>
</th>
<th>
<strong>Large</strong> (lg)<br />
<code>≥1200px</code>
</th>
<th>
<strong>Extra large</strong> (xl)<br />
<code>≥1824px</code>
</th>
</tr>
</thead>
<tbody>
<tr>
<th class="text-left">Max container width</th>
<td>None (auto)</td>
<td>510px</td>
<td>730px</td>
<td>930px</td>
<td>930px</td>
</tr>
<tr>
<th class="text-left">Prop</th>
<td><code>cols="*"</code></td>
<td><code>sm="*"</code></td>
<td><code>md="*"</code></td>
<td><code>lg="*"</code></td>
<td><code>xl="*"</code></td>
</tr>
<tr>
<th class="text-left">number of columns</th>
<td colspan="5">12</td>
</tr>
<tr>
<th class="text-left">Gutter width</th>
<td colspan="5">30px (15px on each side of a column)</td>
</tr>
<tr>
<th class="text-left">Nestable</th>
<td colspan="5">Yes</td>
</tr>
<tr>
<th class="text-left">Offset</th>
<td><code>offset="*"</code></td>
<td><code>offset-sm="*"</code></td>
<td><code>offset-md="*"</code></td>
<td><code>offset-lg="*"</code></td>
<td><code>offset-xl="*"</code></td>
</tr>
<tr>
<th class="text-left">Order</th>
<td><code>order="*"</code></td>
<td><code>order-sm="*"</code></td>
<td><code>order-md="*"</code></td>
<td><code>order-lg="*"</code></td>
<td><code>order-xl="*"</code></td>
</tr>
</tbody>
</table>
</div>
Notes:
- There is no
xsprop. Thecolsprop refers to thexs(smallest) breakpoint.
Container sizes
The following table outlines the default container maximum widths at the various breakpoints.
| Container type | Extra small <768px | Small ≥768px | Medium ≥992px | Large ≥1200px | Extra large ≥1824px |
|---|---|---|---|---|---|
| default | 100% | 510px | 730px | 930px | 930px |
fluid | 100% | 100% | 100% | 100% | 1800px |
fluid="unlimited" | 100% | 100% | 100% | 100% | 100% |
Refer to the Containers <wui-container> section section above for additional information
Auto-layout columns
Utilize breakpoint-specific column classes for easy column sizing without an explicit numbered prop like <wui-col sm="6">.
Equal-width columns
For example, here are two grid layouts that apply to every device and viewport, from xs to xl. Add any number of unit-less classes for each breakpoint you need and every column will be the same width.
<wui-container class="wv-example-row">
<wui-row>
<wui-col>1 of 2</wui-col>
<wui-col>2 of 2</wui-col>
</wui-row>
<wui-row>
<wui-col>1 of 3</wui-col>
<wui-col>2 of 3</wui-col>
<wui-col>3 of 3</wui-col>
</wui-row>
</wui-container>
<!-- wui-grid-equal-width.vue -->
Responsive classes
WUI's grid includes five tiers of predefined classes for building complex responsive layouts. Customize the size of your columns on extra small, small, medium, large, or extra large devices however you see fit.
Stacked to horizontal
Using a single set of sm="*" or sm (boolean for equal width @sm) props, you can create a basic grid system that starts out stacked on extra small devices before becoming horizontal on desktop (medium) devices.
<wui-container class="wv-example-row">
<wui-row>
<wui-col sm="8">col-sm-8</wui-col>
<wui-col sm="4">col-sm-4</wui-col>
</wui-row>
<wui-row>
<wui-col sm>col-sm</wui-col>
<wui-col sm>col-sm</wui-col>
<wui-col sm>col-sm</wui-col>
</wui-row>
</wui-container>
<!-- wui-grid-horizontal-stacked.vue -->
Mix and match
Don't want your columns to simply stack in some grid tiers? Use a combination of different props for each tier as needed. See the example below for a better idea of how it all works.
<wui-container class="wv-example-row">
<!-- Stack the columns on mobile by making one full-width and the other half-width -->
<wui-row>
<wui-col cols="12" md="8">cols="12" md="8"</wui-col>
<wui-col cols="6" md="4">cols="6" md="4"</wui-col>
</wui-row>
<!-- Columns start at 50% wide on mobile and bump up to 33.3% wide on desktop -->
<wui-row>
<wui-col cols="6" md="4">cols="6" md="4"</wui-col>
<wui-col cols="6" md="4">cols="6" md="4"</wui-col>
<wui-col cols="6" md="4">cols="6" md="4"</wui-col>
</wui-row>
<!-- Columns are always 50% wide, on mobile and desktop -->
<wui-row>
<wui-col cols="6">cols="6"</wui-col>
<wui-col cols="6">cols="6"</wui-col>
</wui-row>
</wui-container>
<!-- wui-grid-mix-and-match.vue -->
Offsetting columns
You can offset grid columns in two ways: our responsive offset-* props or the margin utility classes. Grid offset-* props are sized to match columns while margins utility classes are more useful for quick layouts where the width of the offset is variable.
<wui-container fluid class="wv-example-row">
<wui-row>
<wui-col md="4">md="4"</wui-col>
<wui-col md="4" offset-md="4">md="4" offset-md="4"</wui-col>
</wui-row>
<wui-row>
<wui-col md="3" offset-md="3">md="3" offset-md="3"</wui-col>
<wui-col md="3" offset-md="3">md="3" offset-md="3"</wui-col>
</wui-row>
<wui-row>
<wui-col md="6" offset-md="3">md="6" offset-md="3"</wui-col>
</wui-row>
</wui-container>
<!-- wui-grid-offset.vue -->
In addition to column clearing at responsive breakpoints, you may need to reset offsets by setting the offset to 0 at a larger breakpoint:
<wui-container fluid class="wv-example-row">
<wui-row>
<wui-col sm="5" md="6">sm="5" md="6"</wui-col>
<wui-col sm="5" offset-sm="2" md="6" offset-md="0"
>sm="5" offset-sm="2" md="6" offset-md="0"</wui-col
>
</wui-row>
<wui-row>
<wui-col sm="6" md="5" lg="6">sm="6" md="5" lg="6"</wui-col>
<wui-col sm="6" md="5" offset-md="2" lg="6" offset-lg="0"
>sm="6" md="5" offset-md="2" col-lg="6" offset-lg="0"</wui-col
>
</wui-row>
</wui-container>
<!-- wui-grid-offset-reset.vue -->
Column ordering
Easily change the order of grid columns with push-md="*" and pull-md="*" prop.
<wui-container fluid class="wv-example-row">
<wui-row>
<wui-col md="9" push-md="3"
>First in DOM <br />push-md="9" push-md="3"</wui-col
>
<wui-col md="3" pull-md="9"
>Second in DOM <br />pull-md="3" pull-md="9"</wui-col
>
</wui-row>
</wui-container>
<!-- wui-grid-offset.vue -->
Nesting grids
To nest your content with the default grid, add a new <wui-row> and set of <wui-col> components within an existing <wui-col> component. Nested rows should include a set of columns that add up to 12 or fewer (it is not required that you use all 12 available columns).
<wui-container fluid class="wv-example-row">
<wui-row>
<wui-col sm="9">
Level 1: sm="9"
<wui-row>
<wui-col cols="8" sm="6">Level 2: cols="8" sm="6"</wui-col>
<wui-col cols="4" sm="6">Level 2: cols="4" sm="6"</wui-col>
</wui-row>
</wui-col>
</wui-row>
</wui-container>
<!-- wui-grid-nesting.vue -->
Component reference
<wui-container>
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| fluid | Boolean or String | false | When set to true, the component sets a max-width of 1800px across all viewport and device sizes. Or use <wui-container fluid='unlimited'> for a full width container across all viewport and device sizes. |
| tag | String | 'div' | Specify the HTML tag to render instead of the default tag. |
Slots
| Name | Description |
|---|---|
| default | Content to place in the container |
<wui-row>
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| noGutters | Boolean | false | When set, removes the margin from the row and removes the padding from the child columns |
| tag | String | 'div' | Specify the HTML tag to render instead of the default tag |
Slots
| Name | Description |
|---|---|
| default | Content to place in the row |
<wui-col>
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| col | Boolean | false | When true makes an equal width column grid cell spans for xs and up breakpoints |
| cols | Number or String | Number of columns the grid cell spans for xs and up breakpoints | |
| lg | Boolean or Number or String | Number of columns the grid cell spans for lg and up breakpoints | |
| md | Boolean or Number or String | Number of columns the grid cell spans for md and up breakpoints | |
| offset | Number or String | Number of columns the grid cell is offset for xs and up breakpoints | |
| offsetLg | Number or String | Number of columns the grid cell is offset for lg and up breakpoints | |
| offsetMd | Number or String | Number of columns the grid cell is offset for md and up breakpoints | |
| offsetSm | Number or String | Number of columns the grid cell is offset for sm and up breakpoints | |
| offsetXl | Number or String | Number of columns the grid cell is offset for xl and up breakpoints | |
| pull | Number or String | Change the order of the column for xs and up breakpoints (use 'push' on the first DOM item and 'pull' on the second to switch the column order in UI). | |
| pullLg | Number or String | Change the order of the column for lg and up breakpoints. | |
| pullMd | Number or String | Change the order of the column for md and up breakpoints. | |
| pullSm | Number or String | Change the order of the column for sm and up breakpoints. | |
| pullXl | Number or String | Change the order of the column for xl and up breakpoints. | |
| push | Number or String | Change the order of the column for xs and up breakpoints (use 'push' on the first DOM item and 'pull' on the second to switch the column order in UI). | |
| pushLg | Number or String | Change the order of the column for lg and up breakpoints. | |
| pushMd | Number or String | Change the order of the column for md and up breakpoints. | |
| pushSm | Number or String | Change the order of the column for sm and up breakpoints. | |
| pushXl | Number or String | Change the order of the column for xl and up breakpoints. | |
| sm | Boolean or Number or String | Number of columns the grid cell spans for sm and up breakpoints | |
| tag | String | 'div' | Specify the HTML tag to render instead of the default tag. |
| xl | Boolean or Number or String | Number of columns the grid cell spans for xl and up breakpoints |
Slots
| Name | Description |
|---|---|
| default | Content to place in the column |
<wui-grid>
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| gutter | String | Changes the margin around grid items. Supported values for sizes xs, sm, md and for no margin use false (as String) | |
| tag | String | 'div' | Specify the HTML tag to render instead of the default tag |
Slots
| Name | Description |
|---|---|
| default | Content to place in the grid item |
<wui-grid-item>
Properties
<wui-grid-item> inherits all properties from <wui-col>.
Slots
| Name | Description |
|---|---|
| default | Content to place in the grid |
<wui-base-root>
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
height | String | When set, the component adds a style attribute with the passed height and overflow-y: scroll. |
Slots
| Name | Description |
|---|---|
| default | Content to place in the base-root |
