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