CSS API

• Introduction
• CSS API
• Global CSS API
• Local CSS API

Introduction

The CSS API is a set of native CSS custom properties that can be shared across the Gravity Forms Ecosystem.

The Orbital form theme is the default implementation of the Gravity Forms Theme Framework. It can be customized and extended through various methods: code, block settings, WordPress Full Site Editing, Global Styles, stylesheets, and inline styles.

We will be providing much more extensive documentation for the CSS API in the near future to share what is available, how to work with it, and additional examples. So stay tuned!

CSS API

The CSS API itself consists of a set of globally- and locally-scoped custom properties. These can be overridden and customized wherever needed as long as they are scoped to the right selector where they were created. If you are new to CSS custom properties you can read about them! 

Our approach is to favor the global scope as much as possible. You can think of the API has having two primary layers:

Global CSS API

Custom properties globally-scoped to the applicable form wrapper class (gform-theme--foundation or gform-theme--framework). These are properties that need to be available and used across the entire framework. They are the primary and recommended focus whether you want to customize a theme programmatically or via settings by overriding some of these properties. They provide the simplest path to do so without having to worry about writing out a pile of CSS and tracking down specific selectors to be at the right scope. Their default value is set to implement the Orbital form theme.

The syntax and structure for the global custom property names are as follows:

--gf-{area of focus; top level directory if not in /api/ (control, field, form, etc.)}-{css property name}-{state}

Which works like this in practice:

--gf-color-primary

--gf-control-bg-color-focus

.gform-theme--framework {
	--gf-ctrl-bg-color: var(--gf-color-in-ctrl);
	--gf-ctrl-radius: var(--gf-radius);
	--gf-ctrl-shadow: var(--gform-theme-box-shadow-sm);
	--gf-ctrl-color: var(--gf-color-in-ctrl-contrast);
}

Local CSS API

Custom properties locally-scoped to the relevant elements. These apply to more specific selectors such as a control type or form field type and are based on CSS properties themselves. This allows for a more granular, but shared level of local control across selectors. Their default value is set to use the appropriate global CSS API custom property. 

The syntax and structure for the local custom property names are as follows:

--gf-local-{css property name}-{state}

Which works like this in practice:

.gform-theme--framework .gform-theme-field-control {
    /* Local CSS API – which uses the global properties */
	--gf-local-bg-color: var(--gf-ctrl-bg-color);
	--gf-local-radius: var(--gf-ctrl-radius);
	--gf-local-shadow: var(--gf-ctrl-shadow);
	--gf-local-color: var(--gf-ctrl-color);

    /* Styles – which use the local properties */
    background-color: var(--gf-local-bg-color);
	border-radius: var(--gf-local-radius);
	box-shadow: var(--gf-local-shadow);
	color: var(--gf-local-color);
}

.gform-theme--framework .gform-theme-field-control:hover {
    /* Local CSS API Overrides – which once again use different state based global properties */
	--gf-local-bg-color: var(--gf-ctrl-bg-color-hover);
	--gf-local-color: var(--gf-ctrl-color-hover);
}