Theme Framework Upgrade Guide

Introduction

In Gravity Forms 2.8, we refactored the Theme Framework, which powers the Orbital theme, to boost performance by decreasing CSS stylesheet sizes. To do this, we shortened the CSS API property names where appropriate, trying to balance performance, legibility, and maintenance. This is a major update to the Theme Framework and includes breaking changes.

What follows is a guide to upgrading your usage of the Theme Framework from v2.7 to 2.8.

Upgrade Guide

If you have been working with the Theme Framework and integrated it into your add-on or done some custom form theming leveraging the CSS API, you’ll want to follow along below and check to see what if any updates you need to make to what you have used.

Gravity Forms CSS API Properties v2.8

The Theme Framework’s CSS API properties received the following naming updates:

Old	New
gform-theme	gf
background	bg
button	btn
control	ctrl
password	pwd
page	pg
file-upload	file
spacing	space
gf-font-family	gf-font-family-base
progress	prog
description	desc
outside	out
inside	in
box-shadow	shadow
preview	prev
ctrl-file-prev-file	ctrl-file-prev
drop-area	zone
border-radius	radius
strength	str
indicator	ind
product	prod
quantity	quant
required	req
col-gap	gap-x
row-gap	gap-y
vertical	y
horizontal	x
inline-size	width
block-size	height
padding-inline	padding-x
padding-block	padding-y
margin-inline	margin-x
margin-block	margin-y
inset-block-start	inset-y-start
inset-block-end	inset-y-end
inset-inline-start	inset-x-start
inset-inline-end	inset-x-end
table-cell	cell
table-head-cell	head-cell

Polls Add-On CSS API Properties v4.1.1

The Polls Add-On v4.1.1 CSS API properties received the following naming updates:

Old	New
gform-polls-theme	gf-polls
gform-polls-theme-blue-results-color	gf-polls-results-color-blue
gform-polls-theme-green-results-color	gf-polls-results-color-green
gform-polls-theme-red-results-color	gf-polls-results-color-red
gform-polls-theme-orange-results-color	gf-polls-results-color-orange

Survey Add-On CSS API Properties v3.8.1

The Survey Add-On v3.8.1 CSS API properties received the following naming updates:

Old	New
gform-survey-theme	gf-survey
gform-survey-theme-field-likert-row-odd-background-color	gf-survey-field-likert-row-odd-bg-color
gform-survey-theme-icon-control-rank	gf-survey-icon-control-rank

NPM Packages

If you are leveraging the design tokens package in your add-on, specifically any of the Theme Framework based mixins, you’ll want to be sure to update to use v4.0.

Examples

CSS

Upgrading to v2.8

Here is an example of the updates we can make to the Survey add-on to make it Gravity Forms v2.8 ready.

Existing

.gsurvey-likert-choice-label,
.gsurvey-likert-row-label {
    color: var(--gform-theme-control-label-color-primary);
    font-family: var(--gform-theme-control-label-font-family-primary);
    font-size: var(--gform-theme-control-label-font-size-primary);
    font-style: var(--gform-theme-control-label-font-style-primary);
    font-weight: var(--gform-theme-control-label-font-weight-primary);
    letter-spacing: var(--gform-theme-control-label-letter-spacing-primary);
    line-height: var(--gform-theme-control-label-line-height-primary);
}

Updated

.gsurvey-likert-choice-label,
.gsurvey-likert-row-label {
    color: var(--gf-ctrl-label-color-primary);
    font-family: var(--gf-ctrl-label-font-family-primary);
    font-size: var(--gf-ctrl-label-font-size-primary);
    font-style: var(--gf-ctrl-label-font-style-primary);
    font-weight: var(--gf-ctrl-label-font-weight-primary);
    letter-spacing: var(--gf-ctrl-label-letter-spacing-primary);
    line-height: var(--gf-ctrl-label-line-height-primary);
}

Upgrading to v2.8 while maintaining v2.7 compatibility

Here is an example of the updates we can make to the Survey add-on to make it Gravity Forms v2.8 ready while providing v2.7 compatibility. This leverages the ability to provide a fallback for CSS custom properties, where the first value is the preferred (new) custom property, and the second is the fallback (old) should the new not exist.

Existing

See the same code snippet from above.

Updated

.gsurvey-likert-choice-label,
.gsurvey-likert-row-label {
    color: var(--gf-ctrl-label-color-primary, var(--gform-theme-control-label-color-primary));
    font-family: var(--gf-ctrl-label-font-family-primary, var(--gform-theme-control-label-font-family-primary));
    font-size: var(--gf-ctrl-label-font-size-primary, var(--gform-theme-control-label-font-size-primary));
    font-style: var(--gf-ctrl-label-font-style-primary, var(--gform-theme-control-label-font-style-primary));
    font-weight: var(--gf-ctrl-label-font-weight-primary, var(--gform-theme-control-label-font-weight-primary));
    letter-spacing: var(--gf-ctrl-label-letter-spacing-primary, var(--gform-theme-control-label-letter-spacing-primary));
    line-height: var(--gf-ctrl-label-line-height-primary, var(--gform-theme-control-label-line-height-primary));
}

PHP

Here is an example of the updates we can make to the Mollie add-on to make it Gravity Forms v2.8 ready while providing v2.7 compatibility.

$styles = array();

if ( version_compare( GFForms::$version, '2.8-beta-0', '>=' ) ) {
    $styles = array(
        'base' => array(
            'backgroundColor' => 'transparent',
            'color'           => '--gf-ctrl-color',
            'fontSize'        => '--gf-ctrl-font-size',
            'fontWeight'      => '--gf-ctrl-font-weight',
            'letterSpacing'   => '--gf-ctrl-letter-spacing',
            'lineHeight'      => '--gf-ctrl-line-height',
            '::placeholder'   => array(
                'color'         => '--gf-ctrl-placeholder-color',
	        'fontSize'      => '--gf-ctrl-placeholder-font-size',
	        'fontWeight'    => '--gf-ctrl-placeholder-font-weight',
	        'letterSpacing' => '--gf-ctrl-placeholder-letter-spacing',
            ),
        ),
        'invalid' => array(
            'color' => '--gf-ctrl-color-invalid',
        ),
    );
} else {
    $styles = array(
        'base' => array(
            'backgroundColor' => 'transparent',
            'color'           => '--gform-theme-control-color',
            'fontSize'        => '--gform-theme-control-font-size',
            'fontWeight'      => '--gform-theme-control-font-weight',
            'letterSpacing'   => '--gform-theme-control-letter-spacing',
            'lineHeight'      => '--gform-theme-control-line-height',
            '::placeholder'   => array(
                'color'         => '--gform-theme-control-placeholder-color',
	        'fontSize'      => '--gform-theme-control-placeholder-font-size',
	        'fontWeight'    => '--gform-theme-control-placeholder-font-weight',
	        'letterSpacing' => '--gform-theme-control-placeholder-letter-spacing',
            ),
        ),
        'invalid' => array(
            'color' => '--gform-theme-control-color-invalid',
        ),
    );
}

return $styles;

Corollary

After feedback around the compiled stylesheet size and much deliberation, we believe now is the right time to make these changes before Orbital and the Theme Framework become widely adopted.

We know this is a significant update, and we appreciate your understanding. We have always prioritized maintaining backward compatibility, and we take stability very seriously. We have worked hard to ensure that any breaking changes are justifiable and as painless as possible.

We will also be updating our official add-ons that use the Theme Framework to reflect these changes, which is intended to be completed before the public release of v2.8. We’ve got some more performance-based refinements to come, but we don’t plan any more refactoring of the CSS API moving forward