Styling Basics

Using CSS variables in ZingGrid is just like using any CSS variable. By default, the grid will have some default CSS styling to scaffold the overall structure of the grid. Apart from this default styling, ZingGrid allows users to adjust almost every aspect of the grid using CSS variables.

Variables Usage

Using CSS variables is as simple as setting the variables in your CSS under the :root{} or zing-grid selector, like so:

/* preferred usage */
:root {
  --zg-caption-background:red;
}

/* alternative usage */
zing-grid {
  --zg-caption-background:red;
}

CSS Variables Overview

While most styling can be done on the component element itself, ZingGrid is, at the end of the day, a web component utilizing Shadow DOM. We designed the grid to expose as much of the structure to the Light DOM as possible to make styling easy. However, there is functionality hidden away in the shadows that you might want to style.

To navigate this Light/Shadow DOM interplay, we developed a system of CSS variables that allowed us to easily create the various themes that ZingGrid ships with. By default, within the Shadow DOM, you have limited controls to target elements: :host, :host-context, and ::slotted(), with the added limitation that you can only target the slotted element, not its child elements.

On the other hand, CSS variables expose any element at any depth. They also have the added benefit of acting as a public API and can expose the public CSS properties while keeping critical system properties locked away.

The good news for you is all of these variables we used to create the built-in themes are available for you to use! There are many uses to these that you'll discover, but an example of a helpful way to use them is the family of --theme-xxxx-style variables. Instead of setting the same background color on a few elements manually, you can instead set the --theme-background-color variable directly (see below) and all elements associated with that will show the new color.

/* preferred usage */
:root {
  --zg-caption-background:red;
}

/* alternative usage */
zing-grid {
  --zg-caption-background: red;
}

CSS Shadow Parts

Another way to style an element within the shadow tree is through CSS Shadow Parts. Parts of the grid are exposed, and those elements can be styled using ::part(). An element is exposed when it has the part attribute.

For example, style an exposed element within ZGDialog by using ::part(). The element can be styled by any CSS property that would apply to that element. Take this partial markup of ZGDialog:

<dialog class="zg-dialog-dialog" part="dialog">
  ...
  <div class="zg-dialog-body" part="body">
    <div class="zg-dialog-error" part="body-error"></div>
    <div class="zg-dialog-content-wrapper" part="body-content-wrapper"><slot></slot></div>
  </div>
  ...
</dialog>

We can see that several elements are exposed. Styling the body of ZGDialog can easily by taking the value of the part attribute and plugging it into ::part():

zg-dialog::part(body) {
  background-color: red;
}