Beginner Tutorial

Immutable Styles
GitHub Repo NPM Package
Search…
Read Me
Beginner Tutorial
The goal of this tutorial is to introduce immutable styles in a hopefully accessible way.
This tutorial will use a fictitious food app to demonstrate how immutable styles is used for styling web interfaces. For the sake of berevity we will focus on styling a single part of the app – the restaurant card, which displays information for a given restaurant:
Although fairly trivial, the restaurant card provides the perfect fit for illustrating the basic concepts of immutable styles without getting distracted by unnecessary and excessive details.
Setup
The first step is to clone the immutable styles tutorial repository:
1
git clone [email protected]:callum-hart/immutable-styles-tutorial.git
Copied!
Then navigate to the tutorial and install its dependencies:
1
cd immutable-styles-tutorial
2
npm install
Copied!
And start the application:
1
npm run start
Copied!
Finally open localhost:8080 in your favourite browser.
In its current state the restaurant card looks rather unappetising since its markup is unstyled:
The files we are interested in are: src/RestaurantCard.jsx – which contains the restaurant cards markup and: src/RestaurantCard.iss.jsx – which will contain the restaurant cards styles.
You may have noticed RestaurantCard.iss.jsx uses a dual file extension of .iss.jsx. The first part – iss stands for Immutable Style Sheets (or ISS for short). This naming convension allows the compiler to efficiently identify Immutable Style Sheets – whilst preserving JSX syntax highlighting.
Note on Markup
Although this tutorial uses React, it should be noted that immutable styles is markup agnostic – meaning it isn’t coupled or biased to a specific way of generating HTML. Just like a CSS pre-processor – immutable styles generates CSS which can be used on any website – rendered server or client-side.
Boilerplate
RestaurantCard.iss.jsx currently contains boilerplate code typical of any Immutable Style Sheet:
1
1|  /** @jsx createStyle */
2
2|  import { createStyle } from 'immutable-styles';
3
3|
4
4|  export default [];
Copied!
Line 2 imports createStyle from immutable styles – which is a function that generates immutable rulesets. On line 1 the createStyle function is mapped to JSX – meaning any JSX tags in this file will be transpiled to createStyle function calls. Line 4 will export our immutable rulesets.
Styling the Restaurant Card
Lets create our first immutable ruleset. Since it's our first lets make it special ⭐️. We will style the restaurants star rating icons.
Replace line 4 of RestaurantCard.iss.jsx with the following snippet:
1
export default [
2
  <div className="stars">
3
    margin-bottom: 10px;
4
​
5
    <span>
6
      margin-right: 2px;
7
      font-size: 20px;
8
      color: gold;
9
    </span>
10
  </div>
11
];
Copied!
Save the file – and you should see the following:
Next, lets focus on the layout of the restaurant card. The details – the restaurants: rating, name, opening time and summary – should sit to the right of the image. Add the following to RestaurantCard.iss.jsx:
1
export default [
2
  <section className="card">
3
    display: flex;
4
  </section>,
5
​
6
  <div className="details">
7
    flex: 1;
8
    margin: 10px 15px 0;
9
  </div>,
10
​
11
  <div className="stars">
12
    {/* ... */}
13
  </div>
14
];
Copied!
With the ruleset for the restaurant card in place lets improve on its appearance. Replace lines 5 to 7 with the following snippet:
1
<section className="card">
2
  display: flex;
3
  padding: 15px;
4
  border-radius: 4px;
5
  background: white;
6
  box-shadow: 0 2px 2px 0 lightgrey;
7
</section>,
Copied!
And finally, lets spruce up the typography:
1
<h3>
2
  margin: 15px 0;
3
  font-family: sans-serif;
4
</h3>,
5
​
6
<p>
7
  margin: 10px 0;
8
  font-family: sans-serif;
9
  font-size: 14px;
10
  color: slategrey;
11
</p>
Copied!
Save the file, and you should see the following:
So far, all restaurants in our app will have a five star rating. Sadly, in the real world this isn't always the case – some restaurants get a three star rating. Lets update both the markup and styling accordingly.
Firstly, change the default star color from gold to lightgrey:
1
<div className="stars">
2
  {/* ... */}
3
​
4
  <span>
5
    {/* ... */}
6
    color: lightgrey;
7
  </span>
8
</div>
Copied!
Now, in RestaurantCard.jsx add the classname "shining" to the top three stars:
1
10| <div className="stars">
2
11|   <span className="shining">★</span>
3
12|   <span className="shining">★</span>
4
13|   <span className="shining">★</span>
5
14|   <span>★</span>
6
15|   <span>★</span>
7
16| </div>
Copied!
If you save the file – you will notice the first three stars are unstyled:
This is to be expeceted. Immutable styles treat type selectors – in this case <span> – and selectors with a class – in this case <span className="shining"> as different selectors – even though they target the same element type. The type selector <span> only targets elements of type span that do not have a class. Elements of type span with a class – such as "shining" need to be styled individually. This is a key difference between immutable styles and CSS – and is one of the traits that make immutable styles highly deterministic.
Key Point
Styles for an element without a class (such as span) are not applied to the same element type with a class (such as <span className="shining">).
With that in mind, add a ruleset for stars with the class "shining":
1
<div className="stars">
2
  {/* ... */}
3
​
4
  <span>
5
    {/* ... */}
6
  </span>
7
​
8
  <span className="shining">
9
    margin-right: 2px;
10
    font-size: 20px;
11
    color: gold;
12
  </span>
13
</div>
Copied!
Note on Sharing Styles
You may have noticed 2/3rds of the CSS declarations for <span> and <span className="shining"> are the same (each ruleset contains both margin-right and font-size). Immutable styles provides ways to remove duplicate styles, aiding reuse among similar rulesets – however in the interests of not overcomplicating this tutorial won't be introduced yet.
Interactions & Responsiveness
The restaurant card is looking pretty good so far, however it's currently a bit static. It would be nice to add a hover effect and make sure the layout is optimized for mobile devices.
Firstly lets add the hover effect, which is achieved using the pseudo JSX attribute (previously introduced in The Basics guide):
1
<section className="card">
2
  {/* ... */}
3
  transition: background .15s ease-in-out, transform .15s ease-in-out;
4
</section>,
5
​
6
<section className="card" pseudo=":hover">
7
  background: ivory;
8
  transform: scale(1.05);
9
  cursor: pointer;
10
</section>,
Copied!
Now, lets optimize the restaurant card for mobile using the maxWidth JSX attribute:
1
<section className="card">
2
  {/* ... */}
3
</section>,
4
​
5
<section className="card" pseudo=":hover">
6
  {/* ... */}
7
</section>,
8
​
9
<section className="card" maxWidth="600">
10
  margin: 0 20px;
11
​
12
  <img className="image">
13
    display: none;
14
  </img>
15
</section>,
Copied!
And finally lets tighten up the spacing, to allow more content to fit on smaller screen-sizes:
1
<section className="card" maxWidth="600">
2
  {/* ... */}
3
  padding: 0px;
4
​
5
  <img className="image">
6
    {/* ... */}
7
  </img>
8
</section>,
Copied!
If you save the file and open up the browsers console you will see an error has be thrown: [Override Found] The property `padding` has already been defined – and the newly added styles have not been applied. Navigate to your terminal window and you will see the following compile time error:
As the error message shows the padding has been defined twice. The padding set in the first occurance (line 7) is applied to the card on all screen-sizes. The padding set in the second occurance (line 22) is applied to the card on screens up to 600px wide. This means on screen widths between 0px and 600px the padding property is applied twice – which would result in an override, if it weren't for the compiler catching it.
Key Point
The immutable styles compiler can detect and prevent overrides that only occur on specific screen-sizes.
With this in mind, the first padding declaration (line 7) should be moved out to another ruleset that specifically targets screens wider than 600px:
1
<section className="card">
2
  {/* ... */}
3
</section>,
4
​
5
<section className="card" pseudo=":hover">
6
  {/* ... */}
7
</section>,
8
​
9
<section className="card" maxWidth="600">
10
  {/* ... */}
11
​
12
  <img className="image">
13
    {/* ... */}
14
  </img>
15
</section>,
16
​
17
<section className="card" minWidth="601">
18
  padding: 15px;
19
</section>,
Copied!
If you save the file and navigate to your terminal window the compile time error should be resolved, and the latest styles should be visible in your browser.
The Basics
Install
Last modified 3yr ago
Copy link
Contents
Setup
Boilerplate
Styling the Restaurant Card
Interactions & Responsiveness