Theme modes API

In this post, we will introduce Headspin UI Dark Theme API. Dark Theme API is a convenient set of functions that allow users to switch between dark and light modes.

Theme mode hierarchy

Before diving into all the options that we could use, we should understand how dark/light mode logic operates. The hierarchy shown below is in cascade fashion, so each step later will take priority and override the step before.

• App settings
• Match browser/system preference (OPTIONAL)
• User preference

Logic is following:

1. First, we retrieve settings from the Headspin app (dark/light), and that will make the initial theme assumption but has the lowest priority.
2. After we that if API has an option called match media, if data-matchmedia is true this option will be enabled and this will check user browser preference and pull theme from there
3. User preference – This will check the user’s local storage to find if the user set up a theme after the interaction. This step has the highest priority and the first two are like fallback logic until the user interacts with the theme settings UI element.

To recap two steps are logic to set the theme if the user didn’t set up the theme by clicking on toggle/dropdown. The third step will check if the user has some data stored in local storage and set the theme according to that data.

Event API

In the table below we have examples of events that we could use to make more modifications. Init event hooks run only once (initial theme setup after the page is loaded), while Update event hooks are client-side hooks to run before/after each change.

Some usage examples are given below to use as boilerplate for custom logic:

window.addEventListener("theme:hook:beforeInit", function(e){
  e = e || window.event;
  console.log(e.datil);
})

window.addEventListener("theme:hook:afterInit", function(e){
  e = e || window.event;
  console.log(e.datil);
})

window.addEventListener("theme:hook:beforeUpdate", function(e){
  e = e || window.event;
  console.log(e.datil);
})

window.addEventListener("theme:hook:afterUpdate", function(e){
  e = e || window.event;
  console.log(e.datil);
})

Realtime cross tabs events

There is also a real-time sync mechanism for multiple opened tabs in the same browser via Broadcast Channel API. In the example below you could use code to hook after the theme was changed, this method we are using for theme change across multiple tabs, if you need to extend further use the sample code below as a boilerplate.

const realtime = new BroadcastChannel("headspin_theme_channel");

realtime.onmessage = (event) => {
  console.log(event.data);
};