With global styles, you can give your content editors control over site-wide CSS rules.

Global styles - changing primary color

Global Styles Requirements

Implementing global styles requires the following:

JavaScript-Driven CSS

The key to implementing global styles is a JavaScript-based CSS pipeline, where a content file (JSON, Markdown, etc.) can be imported into a main CSS configuration file that is used to set global style rules.

While you can roll your own solution with developer tools like PostCSS, JS-based frameworks like Tailwind CSS are already configured to work in exactly this way.

Example with Tailwind CSS

Note that Tailwind is not required. It is being used as an example below.

For example, Tailwind supports a tailwind.config.js file that is used to set default values for your styles. Using this approach, you can have a file (e.g. content/data/style.json) that holds your global style values

// content/data/style.json

{
  "main": "#f6f1ed"
  // ...
}

And then this file can be imported into and used within your main configuration file.

//
const themeStyle = require('./content/data/style.json')

module.exports = {
  theme: {
    colors: {
      main: themeStyle.main
      // ...
    }
  }
  // ...
}

With Tailwind, configuration options get translated into classes, but can also be used within CSS files.

.button {
  @apply text-main;
}

Modeling Global Styles

The global styles editor is mapped to a ThemeStyle model by default. (This can be customized.) This model can be designed just like any other model with Stackbit, with the nuances for particular content sources noted below.

API Source Model

For headless CMSs, the model can be defined just like any other model in your CMS, but there are a few tangential requirements/suggestions:

  • Singleton Model (optional): If your CMS supports it, make the model a singleton model so that only one instance can be created. (Stackbit only supports one ThemeStyle record.)
  • Write Values to File: Ensure that you are writing the content values to a source file that is imported into your CSS Config file. This often requires a custom-built mechanism.
  • Listening for Content Changes: This mechanism should also listen for content changes. This ensures that when editors make changes (either through Stackbit's visual editor or directly in the CMS), the updated style values are immediately reflected in the preview. The common way to achieve this is by polling the remote source at some regular interval and looking for changes to the style record.

Files Source Model

If using Git CMS (file-based content source), Stackbit will handle writing content directly to the source file that your CSS config file uses. The only requirement is to ensure that the model is specified as the data type and that the file option points to the desired source file.

# Tell Stackbit this is a singleton data model.
type: data
name: ThemeStyle
label: Theme Style
# Source file location.
file: style.json
fieldGroups:
  # ...
fields:
  # ...

Define the fields and groups that best suit your project.

Configuration

The following options are available to adjust how this feature works: