Developing with Scandi
Structure
Tutorials
Styling Components
ScandiPWA uses the BEM methodology and SCSS
To style components, ScandiPWA uses the Block-Element-Modifier (BEM) methodology. BEM is based on assigning meaningful and unique class names to each HTML element we want to style while ensuring that we never need to use any CSS nesting in selectors.
We strive to follow this methodology in the core ScandiPWA theme, and we strongly encourage you to use it when overriding this theme as well.
Benefits of folowing our BEM guidelines:
- The codebase is consistent
- Styles are maintainable and can be re-used by composition with mixes
- Styles can be overriden easily in child themes
The BEM Methodology
This section should serve as a quick introduction to how BEM is used in ScandiPWA. You can read the official BEM Guide. ScandiPWA uses the React variation.
All primary BEM classes are composed of these 2 parts:
<Block>- in UpperCamelCase, the name of the component this element belongs to-<Element>(can be left out) - in UpperCamelCase, a meaningful name of this element (e.g.Container,Button,Divider,Image... whatever identifies the purpose of this element)
Blocks indicate which component owns this element and preserves uniqueness accross all components. By keeping it the same as the component name, you don't need to worry about name-clashes with other components.
The "main" HTML element of each block may be left without a BEM Element. All other elements should have one to indicate their function.
In addition to its primary
<Block[-Element]> class, a block or element may have any number of modifiers of the form:<Block[-Element]>_<booleanModifier>- for boolean modifiers such asisActive,isVisible,isBold, etc. The presence of this modifier indicates that it is "true", and it's absence indicates that it is "false".<Block[-Element]>_<modifierName>_<someValue>- for boolean modifiers with values such ascolor_red,type_primary,size_thumbnail
BEM modifiers can be used to indicate state, available actions, or to distinguish between similar instances of the same element.
BEM in JavaScript
Formatting BEM classes manually with
className would get repetitive, so ScandiPWA uses rebem-jsx to be able to use block and elem to specify the class. As an example, look at the render method of ProductCard:component/ProductCard/ProductCard.component.js (excerpt)
1
render() {
2
const {
3
children,
4
mix,
5
isLoading
6
} = this.props;
7
8
return (
9
<li
10
block="ProductCard"
11
mix={ mix }
12
>
13
<Loader isLoading={ isLoading } />
14
{ this.renderCardWrapper((
15
<>
16
<figure block="ProductCard" elem="Figure">
17
{ this.renderPicture() }
18
</figure>
19
<div block="ProductCard" elem="Content">
20
{ this.renderReviews() }
21
{ this.renderProductPrice() }
22
{ this.renderVisualConfigurableOptions() }
23
{ this.renderTierPrice() }
24
{ this.renderMainDetails() }
25
{ this.renderAdditionalProductDetails() }
26
</div>
27
</>
28
)) }
29
<div block="ProductCard" elem="AdditionalContent">
30
{ children }
31
</div>
32
</li>
33
);
34
}
Copied!
Note that the block is always the same as the name of the component. This ensures consistency and prevents name clashes.
To add modifiers, pass an object with modifiers to the
mods prop. Boolean modifiers will be automatically detected and treated as such.1
renderMainDetails() {
2
const { product: { name } } = this.props;
3
4
return (
5
<p
6
block="ProductCard"
7
elem="Name"
8
mods={ { isLoaded: !!name } }
9
>
10
<TextPlaceholder content={ name } length="medium" />
11
</p>
12
);
13
}
Copied!
Styling Components in SCSS
Selecting BEM
We can take advantage of SCSS amperstand operator to reduce the repetitiveness of selecting BEM classes:
component/ProductCard/ProductCard.style.scss (excerpt, annotated)
1
.ProductCard {
2
// style the block
3
padding-left: 0;
4
min-width: 0;
5
6
&::before {
7
content: none;
8
}
9
10
// & will get replaced with the parent selector, .ProductCard.
11
// so this selects .ProductCard-Content (the Content element
12
// of the ProductCart block
13
&-Content {
14
padding: 1rem;
15
display: flex;
16
flex-wrap: wrap;
17
padding-top: 23px;
18
}
19
20
&-Brand {
21
font-weight: 300;
22
opacity: .5;
23
}
24
25
&-Figure {
26
flex-grow: 1;
27
}
28
29
&-Name {
30
width: 100%;
31
font-size: .9rem;
32
33
// this selector will compile to .ProductCard-Name_isLoaded
34
&_isLoaded {
35
text-overflow: ellipsis;
36
}
37
}
38
}
Copied!
Breakpoints
ScandiPWA defines certain breakpoints that enable you to write viewport width-specific styles. These can be found in the global style directory. To select a specific device, simply use the
@include directive:1
// ...
2
&-Brand {
3
font-weight: 300;
4
opacity: .5;
5
6
// will only affect mobile devices
7
@include mobile {
8
line-height: 1;
9
font-size: 12px;
10
}
11
}
Copied!
CSS Variables
CSS variables are useful when:
- You want to reuse the same value multiple times
- You want to be able to override a value based on the context
- You want to make it more clear what a value represents by naming it
CSS variables are always defined in
:root. That way, re-defining them anywhere else is an easy way to override them. Example:component/CartItem/CartItem.style.scss (simplified & annotated)
1
// we define variables in :root
2
:root {
3
--cart-item-background: #fff;
4
--cart-item-actions-color: #000;
5
}
6
7
.CartItem {
8
&:hover {
9
// we can re-define them to override values
10
--cart-item-actions-color: #222
11
}
12
13
&-Wrapper {
14
background: var(--cart-item-background);
15
}
16
17
&-Delete {
18
height: 35px;
19
color: var(--cart-item-actions-color);
20
}
21
}
Copied!
ScandiPWA uses an auto-prefixer. When compiling, vendor-specific versions of rules are added to make sure they work on most browsers.
Mixes
Sometimes, you may want to allow other components to add additional style rules to a component. For example, the Image component needs to define some styles, but can't predict ahead of time the exact styling features that will be needed for Images in parent components.
The solution is to allow other components to add their own styles to the Image component. The BEM methodology allows this by "mixing" 2 BEM classes together. For example, in the CategoryDetails component, in addition to the regular
Image block, the CategoryDetails-Picture class will be added. Since the element will now have both of these classes, the parent component can additionally style the element with new rules.component/CategoryDetails/CategoryDetails.component.js
1
renderCategoryImagePlaceholder() {
2
return (
3
<Image
4
mix={ { block: 'CategoryDetails', elem: 'Picture' } }
5
objectFit="cover"
6
ratio="custom"
7
isPlaceholder
8
/>
9
);
10
}
Copied!
Note: to allow a component's styles to be mixed, you need to pass the
mix prop to an element in the Component – this won't happen automatically. For example, consider how the Image component passes on the mix prop:component/Image/Image.component.js (simplified excerpt)
1
render() {
2
const {
3
mix
4
} = this.props;
5
6
7
return (
8
<div
9
block="Image"
10
mix={ mix }
11
>
12
{ this.renderImage() }
13
</div>
14
);
15
}
Copied!
Last modified 1yr ago