Grid system

The grid system in Halfmoon is a flexbox based, 12-column system, that can be used to quickly (and easily) build websites and pages which look good on all screen sizes.

How it works

Here's a list of things to understand about the grid system in Halfmoon.

• Columns must be placed inside a container with the .row class for them to work properly.
• Because of flexbox, columns without a specified width will automatically take up equal widths. For example, four instances of .col-sm will each automatically be 25% wide from the small breakpoint and up.
• The maximum number of columns that can be fit into one row is 12. If this number is exceeded, a new row will be automatically created. The column that does the exceeding will drop down to the new row, along with ones coming after it.
• If the column value is specified, the column will take up */12 of the width of the parent container, where * is the value of the column.
• There are five breakpoints — extra small, small, medium, large, and extra large, so columns can have different widths on different screen sizes.
• Grid breakpoints in the class names apply to that one breakpoint and all those above it. For instance, in the above example, .col-sm applies to small, medium, large, and extra large devices, but not the first extra small breakpoint
• Rows and columns have no margin or padding (no gutters). See the practical examples section to see how this works out better for alignment in real life use cases.

The following table explains how the grid system works for the different breakpoints.

With all that said, let's take a look at another example.

Auto-layout columns #

Thanks to flexbox, width of the columns can be set automatically. A few things to note about auto-layout columns:

• Columns with the class .col will take up equal widths on all screen sizes. See the first row in the example below.
• If a column has any of the .col-{breakpoint}-* classes, that column will take up */12 of the width of the parent container. The rest of the columns (with the .col class) will take up equal chunks of what is left. See the second row in the example below.
• If a column has the class .col-auto or .col-{breakpoint}-auto, its width will be based on the natural width of its content. See the third row in the example below.

Responsive columns #

Columns can be made to take up different widths depending on screen sizes using the different class prefixes. Multiple column classes can be used together. This is the best way of making websites responsive.

How it works

Here's a list of things to understand about responsive columns in Halfmoon.

• Columns with breakpoints specified in their class names will maintain their widths as long as the screen width remains above the breakpoint. For example, in the first row above, the columns have the class .col-xl-6, so they will take up half of the parent's width on extra large screens (width > 1200px). Below this width, the columns will "collapse" and take up the full width of their parent container. The same thing also applies to the second row, but there, 768px is the breakpoint.
• Larger column class prefixes are given priority over the smaller ones when applicable. For example, with the third row above, the columns will take up 3/12 of the width on large (and up) screens. As the screen size decreases, each column will take up 4/12 on medium screens, then 5/12 on small screens, and finally stop at 6/12 on extra small screens.

Practical examples #

As mentioned above, columns have no margins or padding by default. In practice, we recommend always using content containers (.content) and cards (.card) inside columns for framing, since they are the main tools for framing content in the main section of the page (opens in new tab).

Equal in-between spacing #

In the previous example with the cards, you may have noticed that the spacing between the cards looks a bit off. This is because the margins between the cards stack up. The in-between spacing can be made equal by adding the .row-eq-spacing (or .row-eq-spacing-{breakpoint} for particular screen sizes) to the rows. The following table explains how it works.

Now, let's fix the last example with the cards using the .row-eq-spacing class.

It is important to remember that equal in-between spacing only works with cards (.card) and content containers (.content) placed directly inside the columns.

Equal in-between spacing works with content containers (.content), therefore, everything can be equally spaced. For instance, in the next example, four alert boxes are placed inside columns with equal in-between spacing. The alerts themselves are placed inside content containers (.content). Here, the .row-eq-spacing-md class is used because we want equal spacing only on medium screens and above, since below this, the columns will "collapse" and take up the full width of their parent container.

A few more things to note

Here's a list of a few more things worth noting about equal in-between spacing:

• The content container (.content) or card (.card) must be the immediate child of the column.
• Only the class for the smallest breakpoint is required even if columns are set to different widths for larger breakpoints. For example, on the first and second rows in the example below, each column has the classes .col-sm-6, .col-md-5, and .col-lg-4. The rows however only have the .row-eq-spacing-sm class because the classes for the larger breakpoints, ie, .row-eq-spacing-md and .row-eq-spacing-lg are not needed.
• When a row overflows, ie, column values exceed 12, a vertical spacer (.v-spacer) should be used right at the point of overflow. This can be hidden for breakpoints where overflow does not occur using utility classes. See the third row in the example below.

Vertical alignment #

Columns can be vertically aligned using flex utilities (opens in new tab).

Horizontal alignment #

Similarly, columns can be horizontally aligned using flex utilities (opens in new tab).

Nested columns #

Columns can be easily nested by placing rows inside of columns. No additional classes are required for this.

Column offsets #

Columns can be offset using .offset-* or .offset-{breakpoint}-*, where * is the left margin of the column (and it can have any value between 0 and 11). For example, the class .offset-md-4 adds a margin to the left of the column equal to the width of .col-md-4.

Please note that you may need to reset the offset in some cases using .offset-{breakpoint}-0. For example, this is done in the fourth row above to prevent overflow on large screens (and up).

Ordering columns #

The visual order of the columns can be controlled using the following classes:

• .order-*/.order-{breakpoint}-*, where * is the order value
• .order-first/.order-{breakpoint}-first
• .order-last/.order-{breakpoint}-last

Adjacent rows #

There are two types of rows in Halfmoon:

• Normal rows
• Rows with equal in-between spacing

Due to there being two types of rows, only four combinations of adjacent rows are possible in a layout:

1. Normal row — normal row
2. Normal row — row with equal in-between spacing
3. Row with equal in-between spacing — row with equal in-between spacing
4. Row with equal in-between spacing — normal row

For combinations 1, 2 and 4, the content-containers (.content) and cards (.card) of the normal rows need to be given the utility classes .mt-0 and/or .mb-0 depending on what comes before and/or after. This is so that everything is properly aligned and spaced vertically.

However, the easier thing to do is to simply add the .row-eq-spacing/.row-eq-spacing-{breakpoint} classes to all the rows. This will automatically fix the spacing and alignment. For instance, in the next example, a fairly complex grid layout (with multiple adjacent rows) is created with ease using these classes.

Building a page #

We built a page in the content and cards section (opens in new tab). Lets improve that page using the grid system to add some content to the side.

In the above example, there is only one row, so there is no point in making it equally spaced using .row-eq-spacing-lg. Moreover, it is strongly recommended that the page wrapper (.page-wrapper), along with the content wrapper (.content-wrapper), is always used to build pages. You can learn more about this in the page building section (opens in new tab) of the docs.

Building a dashboard #

On this section, let's build a dashboard using the things described above (along with some utility classes). The page below is very similar to ones found in real-life dashboards of applications.

In the above example, a .v-spacer is used in the first row to adjust for the overflow of columns. Also, in the row with the Customers and Breakdown cards, the height of the cards are fixed and the overflow-y is set to auto for large screens and up. This is because the Customers card can have varying content, and ideally, the two cards side by side should have the same height to look good.

It is worth repeating that it is strongly recommended that the page wrapper (.page-wrapper), along with the content wrapper (.content-wrapper), is always used to build pages. Again, you can learn more about this in the page building section (opens in new tab) of the docs.

Credits and special thanks #

The grid system in Halfmoon is almost identical to the one found in Bootstrap (with a few changes). Therefore, huge credits (and special thanks) must be given to the Bootstrap team and contributors. The appropriate copyright notice can be found in the CSS files.