| 1 | /**
|
| 2 | * @name Grid
|
| 3 | * @module ionic
|
| 4 | * @description
|
| 5 | *
|
| 6 | * The grid is a powerful mobile-first flexbox system for building custom layouts.
|
| 7 | * It is heavily influenced by [Bootstrap's grid system](http://v4-alpha.getbootstrap.com/layout/grid/).
|
| 8 | *
|
| 9 | * The grid is composed of three units — a grid, row(s) and column(s). Columns will expand to fill their
|
| 10 | * row, and will resize to fit additional columns. It is based on a 12 column layout with different
|
| 11 | * breakpoints based on the screen size. The number of columns and breakpoints can be fully customized
|
| 12 | * using Sass.
|
| 13 | *
|
| 14 | * - [How it works](#how-it-works)
|
| 15 | * - [Grid size](#grid-size)
|
| 16 | * - [Grid attributes](#grid-attributes)
|
| 17 | * - [Default breakpoints](#default-breakpoints)
|
| 18 | * - [Auto-layout columns](#auto-layout-columns)
|
| 19 | * - [Equal-width](#equal-width)
|
| 20 | * - [Setting one column width](#setting-one-column-width)
|
| 21 | * - [Variable-width](#variable-width)
|
| 22 | * - [Responsive attributes](#responsive-attributes)
|
| 23 | * - [All breakpoints](#all-breakpoints)
|
| 24 | * - [Stacked to horizontal](#stacked-to-horizontal)
|
| 25 | * - [Reordering](#reordering)
|
| 26 | * - [Offsetting columns](#offsetting-columns)
|
| 27 | * - [Push and pull](#push-and-pull)
|
| 28 | * - [Alignment](#alignment)
|
| 29 | * - [Vertical Alignment](#vertical-alignment)
|
| 30 | * - [Horizontal Alignment](#horizontal-alignment)
|
| 31 | * - [Customizing the grid](#customizing-the-grid)
|
| 32 | * - [Number of columns and padding](#number-of-columns-and-padding)
|
| 33 | * - [Grid tiers](#grid-tiers)
|
| 34 | *
|
| 35 | *
|
| 36 | * ## How it works
|
| 37 | *
|
| 38 | * The grid is a mobile-first system made up of any number of rows and columns.
|
| 39 | * It is built with flexbox making it extremely responsive. The components that
|
| 40 | * make up the grid can be written as an element (e.g., `<ion-grid>`) or added as
|
| 41 | * an attribute to any element (e.g., `<div ion-row>`).
|
| 42 | *
|
| 43 | * Here's how it works:
|
| 44 | *
|
| 45 | * - Grids act as a container for all rows and columns. Grids take up the full width of their container,
|
| 46 | * but adding the `fixed` attribute will specify the width per screen size, see [grid size](#grid-size) below.
|
| 47 | * - Rows are horizontal groups of columns that line the columns up properly.
|
| 48 | * - Content should be placed within columns, and only columns may be immediate children of rows.
|
| 49 | * - Grid columns without a specified width will automatically have equal widths.
|
| 50 | * For example, four instances of `col-sm` will each automatically be 25% wide for small breakpoints.
|
| 51 | * - Column attributes indicate the number of columns to use out of the default 12 per row.
|
| 52 | * So, `col-4` can be added in order to have three equal-width columns.
|
| 53 | * - Column widths are set as a percentage, so they’re always fluid and sized relative to their parent element.
|
| 54 | * - Columns have padding between individual columns, however, the padding can be removed from the grid and
|
| 55 | * columns by adding `no-padding` on the grid.
|
| 56 | * - There are five grid tiers by default, one for each responsive breakpoint: all breakpoints (extra small),
|
| 57 | * small, medium, large, and extra large.
|
| 58 | * - Grid tiers are based on minimum widths, meaning they apply to their tier and all those larger than it
|
| 59 | * (e.g., `col-sm-4` applies to small, medium, large, and extra large devices).
|
| 60 | * - Grids can easily be customized via Sass variables. See [customizing the grid](#customizing-the-grid).
|
| 61 | *
|
| 62 | * There are some [known bugs with flexbox](https://github.com/philipwalton/flexbugs) that
|
| 63 | * should be checked prior to creating issues with Ionic.
|
| 64 | *
|
| 65 | * ## Grid size
|
| 66 | *
|
| 67 | * By default, the grid will take up 100% width. To set a maximum width based on the screen
|
| 68 | * size add the `fixed` attribute. The maximum width of the grid for each breakpoint is defined
|
| 69 | * in the `$grid-max-widths` Sass variable. For more information, see
|
| 70 | * [customizing the grid](#customizing-the-grid).
|
| 71 | *
|
| 72 | * | Name | Value | Description |
|
| 73 | * |----------|----------|-----------------------------------------------------|
|
| 74 | * | xs | auto | Don't set the grid width for xs screens |
|
| 75 | * | sm | 540px | Set grid width to 540px when (min-width: 576px) |
|
| 76 | * | md | 720px | Set grid width to 720px when (min-width: 768px) |
|
| 77 | * | lg | 960px | Set grid width to 960px when (min-width: 992px) |
|
| 78 | * | xl | 1140px | Set grid width to 1140px when (min-width: 1200px) |
|
| 79 | *
|
| 80 | *
|
| 81 | * ## Grid attributes
|
| 82 | *
|
| 83 | * The grid takes up full width and has padding added to it based on the screen size. There are two
|
| 84 | * attributes that can be used to adjust this behavior.
|
| 85 | *
|
| 86 | * | Property | Description |
|
| 87 | * |-----------------|-------------------------------------------------------------------------------------------------------------------|
|
| 88 | * | no-padding | Removes padding from the grid and immediate children columns. |
|
| 89 | * | fixed | Set a max width based on the screen size. |
|
| 90 | *
|
| 91 | *
|
| 92 | * ## Default breakpoints
|
| 93 | *
|
| 94 | * The default breakpoints are defined by the `$grid-breakpoints` Sass variable. It can be
|
| 95 | * customized to use different values for the breakpoint, rename and add/remove breakpoints.
|
| 96 | * For more information, see [customizing the grid](#customizing-the-grid).
|
| 97 | *
|
| 98 | * | Name | Value | Width Prefix | Offset Prefix | Push Prefix | Pull Prefix | Description |
|
| 99 | * |----------|----------|--------------|---------------|--------------|-------------|---------------------------------------------------|
|
| 100 | * | xs | 0 | `col-` | `offset-` | `push-` | `pull-` | Set columns when (min-width: 0) |
|
| 101 | * | sm | 576px | `col-sm-` | `offset-sm-` | `push-sm-` | `pull-sm-` | Set columns when (min-width: 576px) |
|
| 102 | * | md | 768px | `col-md-` | `offset-md-` | `push-md-` | `pull-md-` | Set columns when (min-width: 768px) |
|
| 103 | * | lg | 992px | `col-lg-` | `offset-lg-` | `push-lg-` | `pull-lg-` | Set columns when (min-width: 992px) |
|
| 104 | * | xl | 1200px | `col-xl-` | `offset-xl-` | `push-xl-` | `pull-xl-` | Set columns when (min-width: 1200px) |
|
| 105 | *
|
| 106 | * _Note: the first breakpoint must have the value set to 0 and all breakpoint values must be in
|
| 107 | * ascending order._
|
| 108 | *
|
| 109 | * ## Auto-layout columns
|
| 110 | *
|
| 111 | * ### Equal-width
|
| 112 | *
|
| 113 | * By default, columns will take up equal width inside of a row for all devices and screen sizes.
|
| 114 | *
|
| 115 | * ```
|
| 116 | * <ion-grid>
|
| 117 | * <ion-row>
|
| 118 | * <ion-col>
|
| 119 | * 1 of 2
|
| 120 | * </ion-col>
|
| 121 | * <ion-col>
|
| 122 | * 2 of 2
|
| 123 | * </ion-col>
|
| 124 | * </ion-row>
|
| 125 | * <ion-row>
|
| 126 | * <ion-col>
|
| 127 | * 1 of 3
|
| 128 | * </ion-col>
|
| 129 | * <ion-col>
|
| 130 | * 2 of 3
|
| 131 | * </ion-col>
|
| 132 | * <ion-col>
|
| 133 | * 3 of 3
|
| 134 | * </ion-col>
|
| 135 | * </ion-row>
|
| 136 | * </ion-grid>
|
| 137 | * ```
|
| 138 | *
|
| 139 | * ### Setting one column width
|
| 140 | *
|
| 141 | * Set the width of one column and the others will automatically resize around it.
|
| 142 | * This can be done using our predefined grid attributes. In the example below,
|
| 143 | * the other columns will resize no matter the width of the center column.
|
| 144 | *
|
| 145 | * ```
|
| 146 | * <ion-grid>
|
| 147 | * <ion-row>
|
| 148 | * <ion-col>
|
| 149 | * 1 of 3
|
| 150 | * </ion-col>
|
| 151 | * <ion-col col-8>
|
| 152 | * 2 of 3 (wider)
|
| 153 | * </ion-col>
|
| 154 | * <ion-col>
|
| 155 | * 3 of 3
|
| 156 | * </ion-col>
|
| 157 | * </ion-row>
|
| 158 | * <ion-row>
|
| 159 | * <ion-col>
|
| 160 | * 1 of 3
|
| 161 | * </ion-col>
|
| 162 | * <ion-col col-6>
|
| 163 | * 2 of 3 (wider)
|
| 164 | * </ion-col>
|
| 165 | * <ion-col>
|
| 166 | * 3 of 3
|
| 167 | * </ion-col>
|
| 168 | * </ion-row>
|
| 169 | * </ion-grid>
|
| 170 | * ```
|
| 171 | *
|
| 172 | * ### Variable-width
|
| 173 | *
|
| 174 | * Using the `col-{breakpoint}-auto` attributes, the column can size itself based on the
|
| 175 | * natural width of its content. This is extremely useful for setting a column width
|
| 176 | * using pixels. The columns next to the variable-width column will resize to fill the row.
|
| 177 | *
|
| 178 | * ```
|
| 179 | * <ion-grid>
|
| 180 | * <ion-row>
|
| 181 | * <ion-col>
|
| 182 | * 1 of 3
|
| 183 | * </ion-col>
|
| 184 | * <ion-col col-auto>
|
| 185 | * Variable width content
|
| 186 | * </ion-col>
|
| 187 | * <ion-col>
|
| 188 | * 3 of 3
|
| 189 | * </ion-col>
|
| 190 | * </ion-row>
|
| 191 | * <ion-row>
|
| 192 | * <ion-col>
|
| 193 | * 1 of 4
|
| 194 | * </ion-col>
|
| 195 | * <ion-col>
|
| 196 | * 2 of 4
|
| 197 | * </ion-col>
|
| 198 | * <ion-col col-auto>
|
| 199 | * <ion-input placeholder="Variable width input"></ion-input>
|
| 200 | * </ion-col>
|
| 201 | * <ion-col>
|
| 202 | * 4 of 4
|
| 203 | * </ion-col>
|
| 204 | * </ion-row>
|
| 205 | * </ion-grid>
|
| 206 | * ```
|
| 207 | *
|
| 208 | *
|
| 209 | * ## Responsive attributes
|
| 210 | *
|
| 211 | * ### All breakpoints
|
| 212 | *
|
| 213 | * To customize a column's width for all devices and screens, add the `col-*`
|
| 214 | * attribute. These attributes tell the column to take up `*` columns out
|
| 215 | * of the available columns.
|
| 216 | *
|
| 217 | * ```
|
| 218 | * <ion-grid>
|
| 219 | * <ion-row>
|
| 220 | * <ion-col col-4>
|
| 221 | * 1 of 4
|
| 222 | * </ion-col>
|
| 223 | * <ion-col col-2>
|
| 224 | * 2 of 4
|
| 225 | * </ion-col>
|
| 226 | * <ion-col col-2>
|
| 227 | * 3 of 4
|
| 228 | * </ion-col>
|
| 229 | * <ion-col col-4>
|
| 230 | * 4 of 4
|
| 231 | * </ion-col>
|
| 232 | * </ion-row>
|
| 233 | * </ion-grid>
|
| 234 | * ```
|
| 235 | *
|
| 236 | * ### Stacked to horizontal
|
| 237 | *
|
| 238 | * Use a combination of width and breakpoint attributes to create a grid that starts out stacked
|
| 239 | * on extra small screens before becoming horizontal on small screens.
|
| 240 | *
|
| 241 | * ```
|
| 242 | * <ion-grid>
|
| 243 | * <ion-row>
|
| 244 | * <ion-col col-12 col-sm>
|
| 245 | * 1 of 4
|
| 246 | * </ion-col>
|
| 247 | * <ion-col col-12 col-sm>
|
| 248 | * 2 of 4
|
| 249 | * </ion-col>
|
| 250 | * <ion-col col-12 col-sm>
|
| 251 | * 3 of 4
|
| 252 | * </ion-col>
|
| 253 | * <ion-col col-12 col-sm>
|
| 254 | * 4 of 4
|
| 255 | * </ion-col>
|
| 256 | * </ion-row>
|
| 257 | * </ion-grid>
|
| 258 | * ```
|
| 259 | *
|
| 260 | *
|
| 261 | * ## Reordering
|
| 262 | *
|
| 263 | * ### Offsetting columns
|
| 264 | *
|
| 265 | * Move columns to the right by adding the `offset-*` attributes. These attributes
|
| 266 | * increase the margin start of the column by `*` columns. For example, in the following
|
| 267 | * grid the last column will be offset by 3 columns and take up 3 columns:
|
| 268 | *
|
| 269 | * ```
|
| 270 | * <ion-grid>
|
| 271 | * <ion-row>
|
| 272 | * <ion-col col-3>
|
| 273 | * 1 of 2
|
| 274 | * </ion-col>
|
| 275 | * <ion-col col-3 offset-3>
|
| 276 | * 2 of 2
|
| 277 | * </ion-col>
|
| 278 | * </ion-row>
|
| 279 | * </ion-grid>
|
| 280 | * ```
|
| 281 | *
|
| 282 | * Offsets can also be added based on screen breakpoints. Here's an example of a
|
| 283 | * grid where the last column will be offset by 3 columns for `md` screens and up:
|
| 284 | *
|
| 285 | * ```
|
| 286 | * <ion-grid>
|
| 287 | * <ion-row>
|
| 288 | * <ion-col col-md-3>
|
| 289 | * 1 of 3
|
| 290 | * </ion-col>
|
| 291 | * <ion-col col-md-3>
|
| 292 | * 2 of 3
|
| 293 | * </ion-col>
|
| 294 | * <ion-col col-md-3 offset-md-3>
|
| 295 | * 3 of 3
|
| 296 | * </ion-col>
|
| 297 | * </ion-row>
|
| 298 | * </ion-grid>
|
| 299 | * ```
|
| 300 | *
|
| 301 | * ### Push and pull
|
| 302 | *
|
| 303 | * Reorder the columns by adding the `push-*` and `pull-*` attributes. These attributes
|
| 304 | * adjust the `left` and `right` of the columns by `*` columns making it easy to reorder
|
| 305 | * columns. For example, in the following grid the column with the `1st col` description
|
| 306 | * will actually be the last column and the `2nd col` will be the first column.
|
| 307 | *
|
| 308 | * ```
|
| 309 | * <ion-grid>
|
| 310 | * <ion-row>
|
| 311 | * <ion-col col-9 push-3>
|
| 312 | * 1 of 2
|
| 313 | * </ion-col>
|
| 314 | * <ion-col col-3 pull-9>
|
| 315 | * 2 of 2
|
| 316 | * </ion-col>
|
| 317 | * </ion-row>
|
| 318 | * </ion-grid>
|
| 319 | * ```
|
| 320 | *
|
| 321 | * Push and pull can also be added based on screen breakpoints. In the following example,
|
| 322 | * the column with the `3rd` column description will actually be the first column for
|
| 323 | * `md` screens and up:
|
| 324 | *
|
| 325 | * ```
|
| 326 | * <ion-grid>
|
| 327 | * <ion-row>
|
| 328 | * <ion-col col-md-6 push-md-3>
|
| 329 | * 1 of 3
|
| 330 | * </ion-col>
|
| 331 | * <ion-col col-md-3 push-md-3>
|
| 332 | * 2 of 3
|
| 333 | * </ion-col>
|
| 334 | * <ion-col col-md-3 pull-md-9>
|
| 335 | * 3 of 3
|
| 336 | * </ion-col>
|
| 337 | * </ion-row>
|
| 338 | * </ion-grid>
|
| 339 | * ```
|
| 340 | *
|
| 341 | *
|
| 342 | * ## Alignment
|
| 343 | *
|
| 344 | * ### Vertical alignment
|
| 345 | *
|
| 346 | * All columns can be vertically aligned inside of a row by adding different
|
| 347 | * attributes to the row. For a list of available attributes, see
|
| 348 | * [row attributes](../Row#row-attributes).
|
| 349 | *
|
| 350 | * ```
|
| 351 | * <ion-grid>
|
| 352 | * <ion-row align-items-start>
|
| 353 | * <ion-col>
|
| 354 | * 1 of 4
|
| 355 | * </ion-col>
|
| 356 | * <ion-col>
|
| 357 | * 2 of 4
|
| 358 | * </ion-col>
|
| 359 | * <ion-col>
|
| 360 | * 3 of 4
|
| 361 | * </ion-col>
|
| 362 | * <ion-col>
|
| 363 | * 4 of 4 <br>#<br>#<br>#
|
| 364 | * </ion-col>
|
| 365 | * </ion-row>
|
| 366 | *
|
| 367 | * <ion-row align-items-center>
|
| 368 | * <ion-col>
|
| 369 | * 1 of 4
|
| 370 | * </ion-col>
|
| 371 | * <ion-col>
|
| 372 | * 2 of 4
|
| 373 | * </ion-col>
|
| 374 | * <ion-col>
|
| 375 | * 3 of 4
|
| 376 | * </ion-col>
|
| 377 | * <ion-col>
|
| 378 | * 4 of 4 <br>#<br>#<br>#
|
| 379 | * </ion-col>
|
| 380 | * </ion-row>
|
| 381 | *
|
| 382 | * <ion-row align-items-end>
|
| 383 | * <ion-col>
|
| 384 | * 1 of 4
|
| 385 | * </ion-col>
|
| 386 | * <ion-col>
|
| 387 | * 2 of 4
|
| 388 | * </ion-col>
|
| 389 | * <ion-col>
|
| 390 | * 3 of 4
|
| 391 | * </ion-col>
|
| 392 | * <ion-col>
|
| 393 | * 4 of 4 <br>#<br>#<br>#
|
| 394 | * </ion-col>
|
| 395 | * </ion-row>
|
| 396 | * </ion-grid>
|
| 397 | * ```
|
| 398 | *
|
| 399 | * Columns can also align themselves differently than other columns by
|
| 400 | * adding the alignment attribute directly to the column. For a list of available
|
| 401 | * attributes, see [column attributes](../Col#column-attributes).
|
| 402 | *
|
| 403 | * ```
|
| 404 | * <ion-grid>
|
| 405 | * <ion-row>
|
| 406 | * <ion-col align-self-start>
|
| 407 | * <div>
|
| 408 | * 1 of 4
|
| 409 | * </div>
|
| 410 | * </ion-col>
|
| 411 | * <ion-col align-self-center>
|
| 412 | * <div>
|
| 413 | * 2 of 4
|
| 414 | * </div>
|
| 415 | * </ion-col>
|
| 416 | * <ion-col align-self-end>
|
| 417 | * <div>
|
| 418 | * 3 of 4
|
| 419 | * </div>
|
| 420 | * </ion-col>
|
| 421 | * <ion-col>
|
| 422 | * <div>
|
| 423 | * 4 of 4 <br>#<br>#<br>#
|
| 424 | * </div>
|
| 425 | * </ion-col>
|
| 426 | * </ion-row>
|
| 427 | * </ion-grid>
|
| 428 | * ```
|
| 429 | *
|
| 430 | * ### Horizontal alignment
|
| 431 | *
|
| 432 | * All columns can be horizontally aligned inside of a row by adding different
|
| 433 | * attributes to the row. For a list of available attributes, see
|
| 434 | * [row attributes](../Row#row-attributes).
|
| 435 | *
|
| 436 | * ```
|
| 437 | * <ion-grid>
|
| 438 | * <ion-row justify-content-start>
|
| 439 | * <ion-col col-3>
|
| 440 | * 1 of 2
|
| 441 | * </ion-col>
|
| 442 | * <ion-col col-3>
|
| 443 | * 2 of 2
|
| 444 | * </ion-col>
|
| 445 | * </ion-row>
|
| 446 | *
|
| 447 | * <ion-row justify-content-center>
|
| 448 | * <ion-col col-3>
|
| 449 | * 1 of 2
|
| 450 | * </ion-col>
|
| 451 | * <ion-col col-3>
|
| 452 | * 2 of 2
|
| 453 | * </ion-col>
|
| 454 | * </ion-row>
|
| 455 | *
|
| 456 | * <ion-row justify-content-end>
|
| 457 | * <ion-col col-3>
|
| 458 | * 1 of 2
|
| 459 | * </ion-col>
|
| 460 | * <ion-col col-3>
|
| 461 | * 2 of 2
|
| 462 | * </ion-col>
|
| 463 | * </ion-row>
|
| 464 | *
|
| 465 | * <ion-row justify-content-around>
|
| 466 | * <ion-col col-3>
|
| 467 | * 1 of 2
|
| 468 | * </ion-col>
|
| 469 | * <ion-col col-3>
|
| 470 | * 2 of 2
|
| 471 | * </ion-col>
|
| 472 | * </ion-row>
|
| 473 | *
|
| 474 | * <ion-row justify-content-between>
|
| 475 | * <ion-col col-3>
|
| 476 | * 1 of 2
|
| 477 | * </ion-col>
|
| 478 | * <ion-col col-3>
|
| 479 | * 2 of 2
|
| 480 | * </ion-col>
|
| 481 | * </ion-row>
|
| 482 | * </ion-grid>
|
| 483 | * ```
|
| 484 | *
|
| 485 | *
|
| 486 | * ## Customizing the grid
|
| 487 | *
|
| 488 | * Using our built-in grid Sass variables and maps, it’s possible to completely customize
|
| 489 | * the predefined grid attributes. Change the number of breakpoints, the media query values,
|
| 490 | * the number of columns, and more.
|
| 491 | *
|
| 492 | * ### Number of columns and padding
|
| 493 | *
|
| 494 | * The number of grid columns and their padding can be modified via Sass variables.
|
| 495 | * `$grid-columns` is used to generate the widths (in percent) of each individual column.
|
| 496 | * `$grid-padding-width` is used for the padding on the grid, while `$grid-padding-widths`
|
| 497 | * allows breakpoint-specific widths that are divided evenly across `padding-left` and
|
| 498 | * `padding-right` as well as `padding-top` and `padding-bottom` of the grid and columns.
|
| 499 | *
|
| 500 | * ```
|
| 501 | * $grid-columns: 12 !default;
|
| 502 | *
|
| 503 | * $grid-padding-width: 10px !default;
|
| 504 | *
|
| 505 | * $grid-padding-widths: (
|
| 506 | * xs: $grid-padding-width,
|
| 507 | * sm: $grid-padding-width,
|
| 508 | * md: $grid-padding-width,
|
| 509 | * lg: $grid-padding-width,
|
| 510 | * xl: $grid-padding-width
|
| 511 | * ) !default;
|
| 512 | * ```
|
| 513 | *
|
| 514 | * ### Grid tiers
|
| 515 | *
|
| 516 | * To customize the breakpoints and their values, override the values of
|
| 517 | * `$grid-breakpoints` and `$grid-max-widths`. For example, to only use
|
| 518 | * 3 breakpoints, the following could be written:
|
| 519 | *
|
| 520 | * ```
|
| 521 | * $grid-breakpoints: (
|
| 522 | * sm: 0,
|
| 523 | * md: 768px,
|
| 524 | * lg: 1024px
|
| 525 | * );
|
| 526 | *
|
| 527 | * $grid-max-widths: (
|
| 528 | * sm: 420px,
|
| 529 | * md: 720px,
|
| 530 | * lg: 960px
|
| 531 | * );
|
| 532 | * ```
|
| 533 | *
|
| 534 | */
|
| 535 | export declare class Grid {
|
| 536 | }
|