CSS flex grid, BEM compliant.
npm install bem-flex-gridCSS flex grid, BEM compliant.
A responsive grid system based on the flex display property that perfectly fits to the viewport in both width and height when needed and lets you design native app layout as well as scrollable web page.
The library comes with 2 syntaxes: __class__ and __attribute__ (or __attr__ for short). Let's take a look at each of them.
The first implementation sticks to the BEM convention (Block, Element and Modifier) using only __CSS class__, but has a more verbose syntax.
Here's an example of a simple grid in the vertical direction (column) that uses the class syntax:
``html`
bem
flex
grid
No worries, we'll explain all this in detail below. For now, let's see how this get converted to the attr syntax.
The second implementation derives from the BEM convention, but has a more concise syntax.
Here are the conversion rules:
- any BEM Block or Element is directly used as an HTML tag __attribute__.
- any BEM Modifier is used to construct the attribute's __value__.
The example above get converted to the attr syntax as follows:
`html`
bem
flex
grid
To get instant access to the library, insert the link tag of the implementation of your choice into your web pages from unpkg CDN.
Class syntax:
`html`
Attr syntax:
`html`
Here's the full markup of the example above using the class syntax:
`html`
bem
flex
grid
> To learn more about the features, check out the demos available for both syntaxes.
Install the package from NPM (or Yarn) and insert the link tag into your web pages or use Sass import for advanced customization.
`bash`
npm i bem-flex-grid
Link tag:
`html`
Sass import:
`scss`
@use "~/bem-flex-grid/src/lib/bem-flex-grid-class.scss";
Link tag:
`html`
Sass import:
`scss`
@use "~/bem-flex-grid/src/lib/bem-flex-grid-attr.scss";
`text`
bem-flex-grid/
├─ dist
│ ├─ bem-flex-grid-attr.css
│ ├─ bem-flex-grid-attr.min.css
│ │
│ ├─ bem-flex-grid-class.css
│ ├─ bem-flex-grid-class.min.css
│ │
│ ├─ bem-flex-grid-core-attr.css
│ ├─ bem-flex-grid-core-attr.min.css
│ │
│ ├─ bem-flex-grid-core-class.css
│ └─ bem-flex-grid-core-class.min.css
└─ src
└─ lib
├─ attr
│ ├─ _card.scss
│ ├─ _core.scss
│ └─ mixins
│ ├─ _card.scss
│ └─ _core.scss
│
├─ class
│ ├─ _card.scss
│ ├─ _core.scss
│ └─ mixins
│ ├─ _card.scss
│ └─ _core.scss
│
├─ variables
│ ├─ _card.scss
│ └─ _core.scss
│
├─ bem-flex-grid-attr.scss
├─ bem-flex-grid-class.scss
│
├─ bem-flex-grid-core-attr.scss
└─ bem-flex-grid-core-class.scss
> The dist folder also contains the __sourcemap__ for each CSS file.
Bem-flex-grid supports the latest, stable releases of all major browsers.
This documentation is based on the class syntax.
But as we said above, it's really easy to switch from one syntax to another.
At core the grid system consists of one .bfg block and one or more .bfg__box elements.
`html`
...
...
...
The box's content can be anything, but the .bfg-card block can be used to fill the box with a card.
> Only one card is allowed per box.
The card's content must be placed inside a .bfg-card__content element.
`html`
...
Then you can add an header to the card using the optional .bfg-card__header element and one or more actions to the header using the optional .bfg-card__action element.
`html`
...
...
...
...
...
Next, insert the .bfg-card block as a child of the .bfg__box element (nesting technique)...
`html`
...
...or use the markup .bfg__box.bfg-card to treat a .bfg__box element as a .bfg-card block too (chaining technique).
`html`
...
Finally, using the markup .bfg.bfg-card simply tells that the .bfg block contains cards elements (content, header and actions) that are not direct children of the .bfg-card block.
This allows you to define the default look and feel for all cards and lets you customize some of them, using the different .bfg-card--* modifiers (you'll see below how to define the card's look and feel).
But order matters! This technique works only when using the .bfg-card--primary modifier as the global look and feel.
` html`
> The .bfg-card block can also be used as a standalone component, outside of the .bfg block.
#### Direction: .bfg--row, .bfg--col
It is required to define the direction the .bfg__box elements are placed in the .bfg block, using .bfg--row or .bfg--col modifiers.
`html`...
> When using .bfg--row modifier, the grid needs the .bfg block width (or its parent width) to be defined (and that's usually the case).
`html`...
> When using .bfg--col modifier, the grid needs the .bfg block height (or its parent height) to be defined (and that's not always the case!).
#### Auto height: .bfg--[B]auto-height
[B] Breakpoint: xl-, lg-, sm-, xs- or none.
By default, the main .bfg block will try to fit to the height of its parent node, by using the height: 100% rule.
Use .bfg--auto-height modifier to apply height: auto rule instead.
`html`...
As the grid is responsive, you can change this behavior at each breakpoint.
Example:
- Fit to the parent height on all screen sizes (even greater than 1200px).
- Use auto-height on large screen (until 992px).
`html`...
#### Wrap onto multiple lines: .bfg--[B]wrap, .bfg--[B]nowrap
[B] Breakpoint: xl-, lg-, sm-, xs- or none.
By default, .bfg__box elements are displayed onto one line and can not leave outside the .bfg block.
To allow .bfg__box elements to wrap as needed onto multiple lines, use the .bfg--wrap modifier.
`html`...
As the grid is responsive, you can change this behavior at each breakpoint.
Example:
- Wrap onto multiple lines on all screen sizes (even greater than 1200px).
- Do not wrap on large screen (until 992px).
- Wrap again on small screen (until 768px).
`html`
...
#### Number of lines: .bfg--[B][N]-lines
[B] Breakpoint: xl-, lg-, sm-, xs- or none.
[N] Number: 2, 3, 4 or 5.
As said above, if you use the markup .bfg.bfg--row.bfg--wrap then .bfg__box elements are placed in the row direction and wrapped onto multiple lines when needed.
But in this case the total height of all .bfg__box elements might be bigger than the .bfg block height itself!
If you know that there's exactly 2 lines of .bfg__box elements, you can constrain them to fit into the .bfg block, by using .bfg--2-lines modifier.
In the same way, use .bfg--3-lines, .bfg--4-lines or .bfg--5-lines modifiers to fit into exactly 3, 4 or 5 lines respectively.
`html`...
`html`...
`html`...
`html`...
> Notice that all the rows will have the same height.
The same pattern applies to the markup .bfg.bfg--col.bfg--wrap.
`html`...
`html`...
`html`...
`html`...
> Notice that all the columns will have the same width.
As the grid is responsive, you can change the number of lines at each breakpoint.
Example:
- Fit boxes on 2 lines on all screen sizes (even greater than 1200px).
- Fit boxes on 3 lines on large screen (until 992px).
- Fit boxes on 4 lines on small screen (until 768px).
`html`
...
#### Gap: .bfg--gap, .bfg--gap-in, .bfg--[B]nogap
[B] Breakpoint: xl-, lg-, sm-, xs- or none.
Add a gap between .bfg__box elements, using .bfg--gap modifier.
`html`...
In this case, the grid is self contained and you don't need to add margin (or padding) to the parent node of the .bfg block.
But if you prefer to define a main margin (or padding) at the parent node of the .bfg block then use .bfg--gap-in modifier.
`html`
...
`html`
...
> The default value of the gap is 1.5rem (see below the Sass variable $bfg-half-gap).
The advantage of using .bfg--gap-in modifier is that you can reduce the main margin (or padding) up to $bfg-half-gap when needed.
Here's an example using the minimal main margin:
`html`
...
The .bfg--gap modifier targets all .bfg__box elements, even those in the inner grids, if any..bfg__box
To remove the gap between elements of an inner grid, use the .bfg--nogap modifier at the __inner grid__ level.
Here's an example with chained grid.
` html`
> See below chained and nested grids to learn how inner grids works.
But the .bfg--nogap modifier can also be useful at the __main grid__ level..bfg-card
Let's say your grid contains some blocks that have a nice border-radius.
In this case, putting the cards next to each other without gap will look weird.
To reset the border-radius of the card's elements, add .bfg--nogap modifier at the main grid.
`html`
As the grid is responsive, you can remove the gap at each breakpoint.
Example:
- Add the gap on all screen sizes (even greater than 1200px).
- Remove the gap on small screen (until 768px).
`html`...
#### Main axis alignment: .bfg--main-[P]
[P] Position: center, end, between, around.
Justify content along the "main" axis using .bfg--main-* modifiers.
By default, .bfg__box elements are packed toward the start line.
`html...
> This is relevant only when the total size of the boxes along the line is less than
(see below the size modifiers for .bfg__box element).
> Then you can choose the distribution mode of the remaining space.#### Cross axis alignment:
.bfg--cross-[P][P] Position:
, center, end.Align items along the "cross" axis using
.bfg--cross-* modifiers.By default,
.bfg__box elements stretch to fill the .bfg block.`html
.........
`#### Order:
[B] Breakpoint:
, lg-, sm-, xs- or none.Reverse the boxes order using
.bfg--reverse modifier.`html
...
`As the grid is responsive, you can reverse the
elements order at each breakpoint.`html
...............
`#### Overflow:
, .bfg--card-content-overflow-[T][T] Type:
, hidden.By default,
.bfg__box and .bfg-card__content elements use the overflow: auto; rule.Use
.bfg--box-overflow-visible modifier on .bfg block to apply the overflow: visible; rule instead on all .bfg__box elements.In the same way, use
.bfg--box-overflow-hidden modifier to apply the overflow: hidden; rule instead.`html
...
...
`Use
modifier on .bfg block to apply the overflow: visible; rule instead on all .bfg-card__content elements.In the same way, use
.bfg--card-content-overflow-hidden modifier to apply the overflow: hidden; rule instead.`html
...
...
`> See below
and .bfg-card__content--overflow-[T] modifiers to apply this behavior to a specific element.#### Disabled:
.bfg--[B]disabled, .bfg--[B]disabled-all[B] Breakpoint:
, lg-, sm-, xs- or none.To disable the grid system for the current
.bfg block only, use .bfg--disabled modifier.To disable the grid system for the current
.bfg block and its chained or nested .bfg blocks, use .bfg--disabled-all modifier.`html
......
`As the grid is responsive, you can disable the grid system at each breakpoint.
Here's an example of disabling the grid system for the current
block only.`html
...............
`$3
#### Size:
[B] Breakpoint:
, lg-, sm-, xs- or none.[S] Size:
1, 2, ..., 11, 12.Define the
.bfg__box element size using .bfg__box--1, .bfg__box--2, ..., .bfg__box--11, .bfg__box--12 modifiers.The total size available for each line is 12.
`html
...
...
...
...
...
...
...
`> If the total size of the boxes along the line is less than
, the remaining space is distributed based on the .bfg--main-[P] modifiers.As the grid is responsive, you can change the
.bfg__box element size at each breakpoint.Example:
- Use
.bfg__box--5 to set the box size to be 5/12 of the available size for all screen size (even greater than 1200px).
- Add .bfg__box--xl-6 to increase the size on extra large screen (until 1200px).
- Add .bfg__box--lg-4 to reduce the size on large screen (until 992px).
- Add .bfg__box--sm-8 to increase the size on small screen (until 768px).
- Add .bfg__box--xs-12 to increase the size on extra small screen (until 576px).`html
...
...
...
`#### Fit:
Use
modifier to indicate that a .bfg__box element should not grow or shrink.Here's an example when using
.bfg--row modifier:`html
`> Defining the box
is optional. If not defined the box width will simply fit to its content.Here's an example when using
.bfg--col modifier:`html
...
...
...
`> Defining the box
is optional. If not defined the box height will simply fit to its content.#### Order:
.bfg__box--[B]first, .bfg__box--[B]last, .bfg__box--[B]in-place[B] Breakpoint:
, lg-, sm-, xs- or none.Change the box order using
.bfg__box--first or .bfg__box--last modifiers.Restore the box order using
.bfg__box--in-place modifier.`html
...
...
`As the grid is responsive, you can change the
element order at each breakpoint.Example:
- Use
.bfg__box--first to place the box in first position on all screen sizes (even greater than 1200px).
- Add .bfg__box--lg-last to place the box in last position on large screen (until 992px).
- Add .bfg__box--sm-in-place to restore the original box position on small screen (until 768px).`html
...
...
...
`#### Overflow:
[T] Type:
, hidden.By default,
.bfg__box element use the overflow: auto; rule.Use
.bfg__box--overflow-visible modifier to apply the overflow: visible; rule instead.Or use
.bfg__box--overflow-hidden modifier to apply the overflow: hidden; rule instead.`html
...
...
...
...
`#### Padding:
When using
modifier, add .bfg__box--nopad modifier to remove the padding of a specific box.`html
...
...
`$3
#### Type:
[T] Type:
, secondary, success, danger, info, warning or any string.For example, add "primary" look and feel to the card's content, header and actions using
.bfg-card--primary modifier.`html
...
...
...
...
...
`> See below the Sass mixin
to create your own card types.$3
#### Overflow:
.bfg-card__content--overflow-[T][T] Type:
, hidden.By default,
.bfg-card__content element use the overflow: auto; rule.Use
.bfg-card__content--overflow-visible modifier to apply the overflow: visible; rule instead.Or use
.bfg-card__content--overflow-hidden modifier to apply the overflow: hidden; rule instead.`html
...
...
...
...
`#### Padding:
Remove the card content padding using
modifier.`html
...
...
...
`$3
#### Chained grid
To chain grids, use markup
to treat a .bfg__box element as a .bfg block too.Example:
See below the
that has both roles:-
.bfg__box.bfg__box--6 as it is an element of its parent .bfg.bfg--col block.
- .bfg.bfg--row as it is a block of its children .bfg__box elements.`html
...
...
...
...
...
`#### Nested grid
An alternative to chained grids consists to simply nest a new
block inside a .bfg__box element.> With this markup, if you use
.bfg--gap modifier, you'll need to add .bfg__box--nopad modifier on the parent node of the nested grid.`html
...
...
...
...
...
`Sass customization
$3
You can change the grid and cards look and feel using Sass, by overriding the default variables value.
scss
// ------ src/lib/variables/_core.scss ------$bfg-breakpoints: (
xs: 576px,
sm: 768px,
lg: 992px,
xl: 1200px
) !default;
$bfg-half-gap: 0.75rem !default;
// ------ src/lib/variables/_card.scss ------
$bfg-card-margin: 1.5rem !default;
$bfg-card-padding: 1rem !default;
$bfg-card-header-height: 2.5rem !default;
$bfg-card-default: (
box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.05),
border-radius: 3px,
border-width: 1px,
header-border-bottom-width: 1px,
header-border-color: #d5d5d5,
header-background-color: #f6f6f6,
header-color: inherit,
content-border-color: #ddd,
content-background-color: #fff,
content-color: inherit
) !default;
$bfg-card-secondary: (
header-border-color: darken(#6c757d, 5),
header-background-color: #6c757d,
header-color: #fff,
) !default;
$bfg-card-success: (
header-border-color: darken(#28a745, 5),
header-background-color: #28a745,
header-color: #fff,
) !default;
$bfg-card-danger: (
header-border-color: darken(#dc3545, 5),
header-background-color: #dc3545,
header-color: #fff,
) !default;
$bfg-card-info: (
header-border-color: darken(#17a2b8, 5),
header-background-color: #17a2b8,
header-color: #fff,
) !default;
$bfg-card-warning: (
header-border-color: darken(#ffc107, 5),
header-background-color: #ffc107,
) !default;
$bfg-card-theme-included: true !default;
`It's important to note that Bem-flex-grid generates __CSS variables__ based on the __Sass variables__.
For example, the Sass variable
becomes the CSS variable --bfg-half-gap.
Thus, the compiled version (dist/bem-flex-grid-class.css for example) contains the following rule:`css
:root {
--bfg-half-gap: 0.75rem;
}
`The same idea applies to the Sass variables of the card.
For example,
contains a box-shadow property.
Thus, the compiled version contains the following rule:`css
:root {
--bfg-card-box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.05);
}
`For cards other than the default card, only the overwritten properties produce CSS variables.
For example,
overwrites the header-background-color property.
Thus, the compiled version contains the following rule:`css
:root {
--bfg-card-secondary-header-background-color: #6c757d;
}
`> Note that the CSS variables for the "primary" card (which are based on the default card) do NOT contain the word
!
> Thus, there's no CSS variable --bfg-card-primary-box-shadow but only --bfg-card-box-shadow.
> On the other hand, the CSS variables for the "secondary" card do contain the word secondary.Example:
Let's customize the boxes gap to be bigger than the default.
`scss
@use "~/bem-flex-grid/src/lib/bem-flex-grid-class.scss" with ($bfg-alf-gap: 1.25rem);
`$3
#### Cards
The
mixin allows you to customize the look and feel of the card's content, header and actions.`scss
@include bfg-card($type, $settings: ());
`By default, Bem-flex-grid generates cards with the following values for the
parameter: primary, secondary, success, danger, info and warning.
But you are free to completely change this naming.Example:
Let's remove the default list of types and define a single type named "fancy".
`scss
@use "~/bem-flex-grid/src/lib/bem-flex-grid-class.scss" as * with ($bfg-card-theme-included: false);@include bfg-card(fancy, (
box-shadow: none,
border-radius: 0px
));
`The
parameter is optional.
In this example, the "fancy" card looks like the default card (picked from the $bfg-card-default), but with a different box-shadow and border-radius.Now, let's use the "fancy" card using the
.bfg-card--fancy modifier (instead of .bfg-card--primary which is no longer available).`html
...
...
...
...
...
`An advanced use case of the card mixin is to create 2 different sets of cards for "light" and "dark" themes.
Example:
scss
@use "../lib/bem-flex-grid-class" as * with (
$bfg-card-theme-included: false, // Let's define the default card using flat design (no box-shadow nor border-radius)
$bfg-card-default: (
box-shadow: none,
border-radius: 0px,
border-width: 1px,
header-border-bottom-width: 1px,
header-border-color: #d5d5d5,
header-background-color: #f6f6f6,
header-color: inherit,
content-border-color: #ddd,
content-background-color: #fff,
content-color: inherit
)
);
// Let's define the "primary" card based on the
$bfg-card-default
@include bfg-card(primary);// Let's define the "warning" card by overwriting some properties
@include bfg-card(warning, (
header-border-color: darken(#ffc107, 5),
header-background-color: #ffc107,
header-color: #fff,
));
body.theme--dark {
// Let's redefine the CSS variables of the "primary" card for the "dark" theme
--bfg-card-box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.2);
--bfg-card-header-border-color: #4a4a4a;
--bfg-card-header-background-color: #3a3a3a;
--bfg-card-header-color: #fff;
--bfg-card-content-border-color: #4a4a4a;
--bfg-card-content-background-color: #2a2a2a;
// Because the "warning" card have a "header-color" property in its definition,
// we have access to the associated CSS variable
--bfg-card-warning-header-color: #000;
}
// Let's imagine this is the global look and feel of our "light" and "dark" themes
body {
background: #fff;
color: #424242;
&.theme--dark {
background: #252525;
color: #dedede;
}
}
#### Media breakpoints
The
mixins lets you add CSS rules that target specific screen sizes.`scss
@include bfg-media-breakpoint-up($size) { ... }@include bfg-media-breakpoint-down($size) { ... }
`> Pick the
value in the following list: xl, lg, sm, xs.Example:
Let's add CSS rules that target only the screen whose size is greater than 992 pixels:
`scss
@include bfg-media-breakpoint-up(lg) {
body { margin: 3rem; }
}
`This is equivalent to:
scss
@media (min-width: 992px) {
body { margin: 3rem; }
}
`Selectors summary
Let's recap the available selectors for both __class__ and __attr__ syntaxes.
$3
####
blockDirection:
-
.bfg--row
- Auto height:
-
, .bfg--xl-auto-height, .bfg--lg-auto-height, .bfg--sm-auto-height, .bfg--xs-auto-heightWrap onto multiple lines:
-
, .bfg--xl-wrap, .bfg--lg-wrap, .bfg--sm-wrap, .bfg--xs-wrap
- , .bfg--xl-nowrap, .bfg--lg-nowrap, .bfg--sm-nowrap, .bfg--xs-nowrapNumber of lines:
-
, .bfg--xl-2-lines, .bfg--lg-2-lines, .bfg--sm-2-lines, .bfg--xs-2-lines
- , .bfg--xl-3-lines, .bfg--lg-3-lines, .bfg--sm-3-lines, .bfg--xs-3-lines
- , .bfg--xl-4-lines, .bfg--lg-4-lines, .bfg--sm-4-lines, .bfg--xs-4-lines
- , .bfg--xl-5-lines, .bfg--lg-5-lines, .bfg--sm-5-lines, .bfg--xs-5-linesGap:
-
-
- , .bfg--xl-nogap, .bfg--lg-nogap, .bfg--sm-nogap, .bfg--xs-nogapMain axis alignment:
-
-
-
- Cross axis alignment:
-
-
- Order:
-
, .bfg--xl-reverse, .bfg--lg-reverse, .bfg--sm-reverse, .bfg--xs-reverseBox overflow:
-
- Card overflow:
-
- Disabled:
-
, .bfg--xl-disabled, .bfg--lg-disabled, .bfg--sm-disabled, .bfg--xs-disabled
- , .bfg--xl-disabled-all, .bfg--lg-disabled-all, .bfg--sm-disabled-all, .bfg--xs-disabled-all####
elementSize:
-
.bfg__box--1, .bfg__box--xl-1, .bfg__box--lg-1, .bfg__box--sm-1, .bfg__box--xs-1
- , .bfg__box--xl-2, .bfg__box--lg-2, .bfg__box--sm-2, .bfg__box--xs-2
- , .bfg__box--xl-3, .bfg__box--lg-3, .bfg__box--sm-3, .bfg__box--xs-3
- ...
- , .bfg__box--xl-11, .bfg__box--lg-11, .bfg__box--sm-11, .bfg__box--xs-11
- , .bfg__box--xl-12, .bfg__box--lg-12, .bfg__box--sm-12, .bfg__box--xs-12Fit:
-
Order:
-
, .bfg__box--xl-first, .bfg__box--lg-first, .bfg__box--sm-first, .bfg__box--xs-first
- , .bfg__box--xl-last, .bfg__box--lg-last, .bfg__box--sm-last, .bfg__box--xs-last
- , .bfg__box--xl-in-place, .bfg__box--lg-in-place, .bfg__box--sm-in-place, .bfg__box--xs-in-placeOverflow:
-
- Padding:
-
####
blockType:
-
.bfg-card--primary, .bfg-card--secondary, .bfg-card--success, .bfg-card--danger, .bfg-card--info, .bfg-card--warning
- ...####
elementOverflow:
-
.bfg-card__content--overflow-visible
- Padding:
-
$3
####
block attributeDirection:
-
bfg="row | col"Auto height:
-
Wrap onto multiple lines:
-
- Number of lines:
-
-
-
- Gap:
-
Main axis alignment:
-
Cross axis alignment:
-
Order:
-
Box overflow:
-
Card overflow:
-
Disabled:
-
- ####
element attributeSize:
-
bfg__box="1 | xl-1 | lg-1 | sm-1 | xs-1"
-
-
- ...
-
- Fit:
-
Order:
-
-
- Overflow:
-
Padding:
-
####
block attributeType:
-
bfg-card="primary | secondary | success | danger | info | warning"
- ...####
element attributeOverflow:
-
bfg-card__content="overflow-visible | overflow-hidden"Padding:
-
Contribute
bash
git clone https://github.com/avine/bem-flex-grid.gitcd bem-flex-grid
npm i
Open showcase in your favorite browser
npm startCompile SASS (
src/lib/) to CSS (dist/)
npm run buildBuild HTML documentation (
src/index.html) from README.md
npm run readme