Theming

Start of documentation content

Formally has been designed to allow easy theming.

Formally has default CSS designed to inherit your page styles, and to be themed.

If you wish to customise the HTML or other behaviour of Formally instead try the React SDK Custom Controls.

Theme variables (recommended)

CSS Custom Variables (aka CSS Custom Properties) builds upon the default CSS that Formally provides, and makes for easy upgrades in the future. Visit MDN to read generally about CSS Custom Properties.

Using CSS Variables is the recommended approach to theming as it doesn't fork Formally's default CSS.

A complete list of the CSS Variables that Formally understands is at the end of the page (see "List of all CSS Variables that Formally supports" heading).

How to know which theme variables to use

In your browser developer tools inspect the element that you wish to theme and ensure that element is selected.

Tip: if you're looking to customise radio buttons or checkboxes look for the ::before or ::after pseudo elements.

In the list of styles associated with the element look for CSS classes that begin with "formally-" (eg "formally-input") and then look for CSS property values that contain var(-- (eg var(--formally-text-border-radius)).

Note: Only CSS properties containing Formally CSS Variables can be configured. Please contact support if there isn't a CSS variable for the CSS Property that you wish to configure.

With the CSS Variable name you can now override that variable to change that CSS property value.

List of all CSS Variables that Formally supports

CSS Variable (CSS Property)	Type	About	Default value
`--formally-autosuggestion-list-height`	Length	Auto suggest items list height	`400px`
`--formally-color-autosuggestion-icon`	Color	Auto suggest icon colour	`var(--formally-color-brand)`
`--formally-color-autosuggestion-selected-list-item-border`	Color	Auto suggest list item border colour	`var(--formally-color-border-light)`
`--formally-color-autosuggestion-selected-list-item-text`	Color	Auto suggest selected list item text colour	`var(--formally-color-content)`
`--formally-color-autosuggestion-selected-list-item-hover`	Color	Auto suggest selected list item hover colour	`var(--formally-color-brand-light)`
`--formally-error-border-width`	Length	Thickness of error border	`2px`
`--formally-border-radius`	Length	Radius of fields	`4px`
`--formally-text-border-radius`	Length	Radius of text fields (FreeText)	`4px`
`--formally-select-border-radius`	Length	Radius of dropdown (Select)	`4px`
`--formally-button-radius`	Length	Radius of buttons	`6px`
`--formally-dateinput-border-radius`	Length	Radius of date inputs	`4px`
`--formally-input-border-width`	Length	Border thickness (width) of textural inputs (FreeText etc.)	`1px`
`--formally-color-locale-picker-border`	Color	Locale picker border colour	`var(--formally-color-white)`
`--formally-button-padding-horizontal`	Length	Padding of buttons (horizontal)	`24px`
`--formally-button-padding-vertical`	Length	Padding of buttons (vertical)	`0.75rem`
`--formally-button-delete-width`	Length	Width of delete button within a Repeater	`3em`
`--formally-button-delete-height`	Length	Height of delete button within a Repeater	`2em`
`--formally-xs-button-group-flex-direction`	—	Button group alignment.	`column`
`--formally-md-button-group-flex-direction`	—	Button group alignment.	`row`
`--formally-color-button-border-primary`	Color	Primary Button border colour. Primary buttons are usually 'Next' or 'Submit' buttons, but not 'Previous'.	`var(--formally-color-brand)`
`--formally-color-button-text-primary`	Color	Primary Button text colour. Primary buttons are usually 'Next' or 'Submit' buttons, but not 'Previous'.	`var(--formally-color-white)`
`--formally-color-button-bg-primary`	Color	Primary Button background colour. Primary buttons are usually 'Next' or 'Submit' buttons, but not 'Previous'.	`var(--formally-color-brand)`
`--formally-color-button-bg-primary-dark`	Color	Primary Button background colour dark variation. Primary buttons are usually 'Next' or 'Submit' buttons, but not 'Previous'.	`var(--formally-color-brand-dark)`
`--formally-color-button-bg-primary-darker`	Color	Primary Button background colour darker variation. Primary buttons are usually 'Next' or 'Submit' buttons, but not 'Previous'.	`var(--formally-color-brand-darker)`
`--formally-color-button-border-secondary`	Color	Secondary Button border colour. Secondary buttons are usually 'Previous' buttons, but not 'Next' or 'Submit' buttons.	`var(--formally-color-brand)`
`--formally-color-button-text-secondary`	Color	Secondary Button text colour. Secondary buttons are usually 'Previous' buttons, but not 'Next' or 'Submit' buttons.	`var(--formally-color-brand)`
`--formally-color-button-bg-secondary`	Color	Secondary Button background colour. Secondary buttons are usually 'Previous' buttons, but not 'Next' or 'Submit' buttons.	`var(--formally-color-white)`
`--formally-color-button-bg-secondary-dark`	Color	Secondary Button background colour dark variation. Secondary buttons are usually 'Previous' buttons, but not 'Next' or 'Submit' buttons.	`var(--formally-color-brand-lighter)`
`--formally-color-button-bg-secondary-darker`	Color	Secondary Button background colour darker variation. Secondary buttons are usually 'Previous' buttons, but not 'Next' or 'Submit' buttons.	`var(--formally-color-brand-light)`
`--formally-button-group-margin-block`	—	Button group (previous / next / submit buttons) margin	`3.125rem 0`
`--formally-button-min-tap-size`	Length	Accessible tap-size for buttons etc. Used in the a11y-target-size mixin	`48px`
`--formally-fieldset-border`	—	Fieldset border	`solid 1px var(--formally-color-border-dark)`
`--formally-fieldset-border-radius`	Length	Fieldset border radius	`var(--formally-border-radius)`
`--formally-fieldset-padding`	—	Fieldset padding	`0 var(--formally-field-padding-horizontal) var(--formally-field-padding-vertical) var(--formally-field-padding-horizontal)`
`--formally-fieldset-legend-padding`	—	Fieldset legend padding	`var(--formally-field-padding-vertical) var(--formally-field-padding-horizontal)`
`--formally-icon-size`	Length	Size of icons	`16px`
`--formally-stroke-width`	Number	SVG stroke width for icons	`2`
`--formally-stroke-linecap`	—	SVG stroke-linecap for icons	`butt`
`--formally-stroke-linejoin`	—	SVG stroke-linejoin for icons	`miter`
`--formally-input-height`	Length	Text input (free text) field type height	`3rem`
`--formally-color-input`	Color	Text input (free text) colour	`var(--formally-color-content)`
`--formally-color-input-bg`	Color	Text input (free text) background colour	`var(--formally-color-background)`
`--formally-color-input-select-bg`	Color	Input select background colour	`var(--formally-color-brand)`
`--formally-color-input-border`	Color	Input border colour	`var(--formally-color-border-light)`
`--formally-color-input-border-focus`	Color	Input border colour when in focus (when the field has been navigated to by the user)	`var(--formally-color-brand)`
`--formally-color-input-border-warning`	Color	Input border colour when the field has a warning (error)	`var(--formally-color-warn)`
`--formally-input-border-size-warning`	Length	Input border width when the field has a warning (error)	`var(--formally-error-border-width)`
`--formally-color-input-placeholder`	Color	Input placeholder colour	`var(--formally-color-placeholder)`
`--formally-color-input-select-chevron`	Color	Select field chevron color (colour)	`var(--formally-color-brand)`
`--formally-input-liveupload-status-font-size`	Length	Live upload status font-size	`var(--formally-font-size-smaller)`
`--formally-input-liveupload-status--success-border`	—	Live upload status success border colour	`0`
`--formally-color-input-liveupload-status--success`	Color	Live upload status success text colour	`var(--formally-color-brand)`
`--formally-color-input-liveupload-status--success-background`	Color	Live upload status success background colour	`var(--formally-color-background)`
`--formally-input-liveupload-status--error-border`	—	Live upload status error border colour	`solid 1px var(--formally-color-warn)`
`--formally-color-input-liveupload-status--error-background`	Color	Live upload status error background colour	`var(--formally-color-background)`
`--formally-color-input-liveupload-status--error`	Color	Live upload status error text colour	`var(--formally-color-warn)`
`--formally-color-choice-bg`	Color	Multichoice (checkbox/radio) background colour	`var(--formally-color-white)`
`--formally-color-choice-bg-selected`	Color	Multichoice (checkbox/radio) background colour of selected item	`var(--formally-color-brand)`
`--formally-color-choice-border`	Color	Multichoice (checkbox/radio) border colour	`var(--formally-color-border-light)`
`--formally-color-choice-border-checked`	Color	Multichoice (checkbox/radio) border colour of selected item	`var(--formally-color-brand)`
`--formally-choice-checkbox-size`	Length	Checkbox size (width/height)	`1.5rem`
`--formally-choice-checkbox-border-radius`	Length	Checkbox border radius	`4px`
`--formally-color-checkbox-tick`	Color	Checkbox ticked colour	`var(--formally-color-white)`
`--formally-choice-radio-size`	Length	Radio size (width/height)	`1.5rem`
`--formally-color-brand-lighter`	Color	Colour variable for lighter brand colour	`color-mix(in srgb, transparent, var(--formally-color-brand) 10%)`
`--formally-color-brand-light`	Color	Colour variable for light brand colour	`color-mix(in srgb, transparent, var(--formally-color-brand) 20%)`
`--formally-color-brand-pastel`	Color		`#e4caff`
`--formally-color-brand`	Color	Colour variable for brand colour	`#6100ff`
`--formally-color-brand-dark`	Color	Colour variable for dark brand colour	`#5000c9`
`--formally-color-brand-darker`	Color	Colour variable for darker brand colour	`#430099`
`--formally-color-grey`	Color	Colour variable for grey. This variable isn't used directly. You should probably override where this is used instead of overriding this variable.	`#595959`
`--formally-color-grey-light`	Color	Colour variable for grey. This variable isn't used directly. You should probably override where this is used instead of overriding this variable.	`#d0d0d0`
`--formally-color-black`	Color	Colour variable for black.	`black`
`--formally-color-white`	Color	Colour variable for white.	`white`
`--formally-color-red`	Color		`#b5031f`
`--formally-color-content`	Color	Colour variable for content.	`var(--formally-color-black)`
`--formally-color-background`	Color	Colour variable for background.	`var(--formally-color-white)`
`--formally-color-modal-background`	Color		`color-mix(in srgb, transparent, var(--formally-color-grey) 90%)`
`--formally-color-placeholder`	Color	Colour variable for placeholder text. Accessibility-wise placeholder text may be confused for an actual response, so placeholder text isn't recommended.	`var(--formally-color-grey)`
`--formally-color-warn`	Color	Colour variable for warning (error) messages	`var(--formally-color-red)`
`--formally-color-focus`	Color	Colour variable for field focus ring	`var(--formally-color-brand)`
`--formally-color-hint`	Color	Colour variable for hint text	`var(--formally-color-grey)`
`--formally-color-label`	Color	Colour variable for label text	`var(--formally-color-content)`
`--formally-color-border-light`	Color	Light colour variation of border	`var(--formally-color-grey)`
`--formally-color-border-dark`	Color	Dark colour variation of border	`var(--formally-color-black)`
`--formally-color-progress-indicator-bg`	Color	Progress indicator background colour. Progress indicator is the (eg) 'Page 1 of 5' message at the top of forms.	`var(--formally-color-grey-light)`
`--formally-color-progress-indicator-bg-previous`	Color	Page indicator previous page background colour. Progress indicator is the (eg) 'Page 1 of 5' message at the top of forms.	`var(--formally-color-brand)`
`--formally-color-progress-indicator-bg-active`	Color	Page indicator current page background colour. Progress indicator is the (eg) 'Page 1 of 5' message at the top of forms.	`var(--formally-color-brand)`
`--formally-color-slider-track-bg`	Color	Range slider background colour	`var(--formally-color-brand-pastel)`
`--formally-slider-track-height`	Length	Range slider track height	`0.5rem`
`--formally-slider-track-border-radius`	Length	Range slider track radius	`0.5rem`
`--formally-slider-margin-top`	Length	Range slider margin top	`1.5625rem`
`--formally-slider-thumb-size-pixels`	Length	Range slider thumb (dragable widget) size (width/height)	`2.75rem`
`--formally-slider-thumb-margin-top`	Length	Range slider thumb (dragable widget) margin top	`-1.1875rem`
`--formally-color-slider-thumb-bg`	Color	Range slider thumb background colour	`var(--formally-color-white)`
`--formally-color-slider-thumb-border`	Color	Range slider thumb border colour	`var(--formally-color-brand)`
`--formally-slider-thumb-border-width`	Length	Range slider thumb border width	`0.75rem`
`--formally-slider-thumb-border`	—	Range slider thumb border (shorthand style)	`var(--formally-slider-thumb-border-width) solid var(--formally-color-slider-thumb-border)`
`--formally-color-slider-unset`	Color	Range slider colour when unselected / without value	`#999`
`--formally-color-repeater-border`	Color	Repeater border colour.	`var(--formally-color-black)`
`--formally-repeater-title-padding-inline`	Length	Repeater inline padding. Used to indent repeating items.	`12px`
`--formally-repeater-delete-button-font-size`	Length	Repeater delete button font size.	`var(--formally-font-size-larger)`
`--formally-color-repeater-delete-button-hover-background`	Color	Repeater delete button background color	`var(--formally-color-brand-light)`
`--formally-max-width`	Length	Maximum width of the Formally container	`640px`
`--formally-space-xs-num`	Number	Spacing unit XS (extra small). Override with a unitless number, e.g. 10 not 10px.	`8`
`--formally-space-xs-px`	Length	Derived from --formally-space-xs-num. Override that variable instead.	`calc(var(--formally-space-xs-num) * 1px)`
`--formally-space-xs-rem`	Length	Derived from --formally-space-xs-num. Override that variable instead.	`calc(var(--formally-space-xs-num) / 16 * 1rem)`
`--formally-space-sm-num`	Number	Spacing unit SM (small). Override with a unitless number, e.g. 10 not 10px.	`12`
`--formally-space-sm-px`	Length	Derived from --formally-space-sm-num. Override that variable instead.	`calc(var(--formally-space-sm-num) * 1px)`
`--formally-space-sm-rem`	Length	Derived from --formally-space-sm-num. Override that variable instead.	`calc(var(--formally-space-sm-num) / 16 * 1rem)`
`--formally-space-md-num`	Number	Spacing unit MD (medium). Override with a unitless number, e.g. 10 not 10px.	`16`
`--formally-space-md-px`	Length	Derived from --formally-space-md-num. Override that variable instead.	`calc(var(--formally-space-md-num) * 1px)`
`--formally-space-md-rem`	Length	Derived from --formally-space-md-num. Override that variable instead.	`calc(var(--formally-space-md-num) / 16 * 1rem)`
`--formally-space-lg-num`	Number	Spacing unit LG (large). Override with a unitless number, e.g. 10 not 10px.	`20`
`--formally-space-lg-px`	Length	Derived from --formally-space-lg-num. Override that variable instead.	`calc(var(--formally-space-lg-num) * 1px)`
`--formally-space-lg-rem`	Length	Derived from --formally-space-lg-num. Override that variable instead.	`calc(var(--formally-space-lg-num) / 16 * 1rem)`
`--formally-space-xl-num`	Number	Spacing unit XL (extra large). Override with a unitless number, e.g. 10 not 10px.	`32`
`--formally-space-xl-px`	Length	Derived from --formally-space-xl-num. Override that variable instead.	`calc(var(--formally-space-xl-num) * 1px)`
`--formally-space-xl-rem`	Length	Derived from --formally-space-xl-num. Override that variable instead.	`calc(var(--formally-space-xl-num) / 16 * 1rem)`
`--formally-node-gap-num`	Number	Vertical distance between Formally nodes (fields). Override with a unitless number, e.g. 10 not 10px.	`28`
`--formally-node-gap-px`	Length	Derived from --formally-node-gap-num. Override that variable instead.	`calc(var(--formally-node-gap-num) * 1px)`
`--formally-node-gap-rem`	Length	Derived from --formally-node-gap-num. Override that variable instead.	`calc(var(--formally-node-gap-num) / 16 * 1rem)`
`--formally-field-padding-vertical`	Length	Form field padding (vertical)	`0.75rem`
`--formally-field-padding-horizontal`	Length	Form field padding (horizontal)	`16px`
`--formally-submit-pending-font-size`	Length	Font size of message that appears when submitting and waiting for a network response	`1em`
`--formally-submit-pending-text-align`	—	Text alignment of container of message that appears when submitting and waiting for a network response	`right`
`--formally-font-family`	—	Default font family.	`sans-serif`
`--formally-font-size-smaller`	Length	Smaller font size used for less important small print	`0.875em`
`--formally-font-size-larger`	Length	Larger font size used for important text	`1.125em`
`--formally-label-font-weight`	—	Label boldness	`bold`
`--formally-label-font-size`	—	Label font size	`inherit`

Would you like to style something not mentioned here? Please let us know.

Customising CSS Variables in React

React itself has a variety of methods of applying CSS.

This example uses inline style, however there are alternative examples that follow.

import { Formally } from 'formally';
import 'formally/build/styles.min.css';

export const MyForm = () => (
  <div style={{ '--formally-color-brand': 'red' }}>
    <Formally />
  </div>
);

Customising CSS Variables in React with Next.js

// _app.tsx

import 'formally/build/styles.min.css';
import './my-formally-theme.css';

const MyApp = ({ Component, pageProps }) => (
  return <Component {...pageProps} />
);

export default MyApp;

/* my-formally-theme.css */
.formally-container {
  /* configure any Formally CSS Variables here */
  --formally-color-brand: red;
}

Customising Theme Variables in React with Styled Components

import 'formally/build/styles.min.css';

const FormallyWrapper = styled.div`
  --formally-color-brand: red;
`;

export const MyForm = () => (
  <FormallyWrapper>
    <Formally />
  </FormallyWrapper>
);

Customising Theme Variables in React with CSS Modules

import 'formally/build/styles.min.css';
import styles from './my-formally-theme.module.css';

export const MyForm = () => (
  <div className={styles.myFormallyWrapper}>
    <Formally />
  </div>
);

/* my-formally-theme.module.css */
.myFormallyWrapper {
  /* configure any Formally CSS Variables here */
  --formally-color-brand: red;
}

Customising Theme Variables in HTML / CSS

<link rel="stylesheet" href="https://form-data.getformally.com/styles.min.css" />
<style>
.formally-container {
  /* configure any Formally CSS Variables here */
  --formally-color-brand: red;
}
</style>

Overriding Formally CSS classes

This approach uses Formally CSS but also your own CSS that matches CSS classes used by Formally.

This is slightly risky because if you upgrade to a later version of Formally the CSS classes may change. Formally makes no guarantees about CSS class name stability.

However if you test your CSS after you upgrade this may be an appropriate choice.

Warning: Considering entirely Custom CSS?

From a technical standpoint Formally's CSS is optional and as such developers may ignore it and instead use their own CSS.

However this isn't recommended as you will incur a significant development effort to start with, and an ongoing maintenance burden when upgrading to newer versions of Formally.

Instead please consider whether configuring Formally's CSS Variables could sufficient, and please feel free to suggest new CSS Variables (contact support!).

If you choose this approach please ensure that you use a specific version of Formally via NPM or UNPKG to avoid breaking changes. Do not use our CDN hosted version which is always the latest version and may have breaking changes against your custom CSS.

We do not support or recommend this approach.

Search

Table of contents