Edit page

Forms Theming

To make forms theming easy and robust, form components have many theming options in common.

General naming convention for CSS custom properties looks as follows:

--rui-FormField--[<TYPE>]--[<MODIFICATION>]__[<ELEMENT>--[<ELEMENT TYPE]]--[<INTERACTION STATE>]__<PROPERTY>

Items in brackets are optional. As you read on you will notice some theming option groups may have less complicated conventions (that are still subset of the naming system above).

Basic Theming

The following theme options define basic appearance of all form fields.

Custom PropertyDescription
--rui-FormField__label__colorLabel text color
--rui-FormField__label__font-sizeLabel font size
--rui-FormField__help-text__font-sizeHelp text font size
--rui-FormField__help-text__font-styleHelp text font style, e.g. italic
--rui-FormField__help-text__colorHelp text color
--rui-FormField--required__signText appended to required input labels
--rui-FormField--required__sign__colorColor of text appended to required input labels

Horizontal Layout

Options for fields that support horizontal layout.

Custom PropertyDescription
--rui-FormField--horizontal__label__text-alignText alignment of labels in horizontal layout
--rui-FormField--horizontal__label__min-widthMinimum width of labels in horizontal layout
--rui-FormField--horizontal__label__widthDefault width of labels in horizontal layout
--rui-FormField--horizontal__label__padding-yTop and bottom padding to tweak vertical alignment of labels
--rui-FormField--horizontal__label__vertical-alignmentVertical box alignment of labels in horizontal layout
--rui-FormField--horizontal__field__vertical-alignmentVertical box alignment of fields in horizontal layout
--rui-FormField--horizontal--full-width__label__widthDefault width of labels in full-width horizontal layout

Box Fields

Options shared by box form controls. This includes TextField, TextArea, and SelectField.

Custom PropertyDescription
--rui-FormField--box__border-widthControl border width
--rui-FormField--box__border-radiusControl corner radius
--rui-FormField--box__input__widthDefault text input and select box width
--rui-FormField--box__input__min-widthMinimum text input and select box width
--rui-FormField--box__placeholder__colorPlaceholder text color

Example:

Box Field Variants

Theming options for box form controls. Naming convention looks as follows:

--rui-FormField--box--<VISUAL VARIANT>--<INTERACTION STATE>__<PROPERTY>

Where:

  • <VISUAL VARIANT> is one of filled or outline,
  • <INTERACTION STATE> is one of default, hover, focus, or disabled,
  • <PROPERTY> is one of color, border-color, background, box-shadow, or surrounding-text-color (the last one being available only for default and disabled interaction states).

Example:

Box Field Sizes

Available sizes can be adjusted as follows:

--rui-FormField--box--<SIZE>__<PROPERTY>

Where:

  • <SIZE> is one of small, medium, or large
  • <PROPERTY> is one of height, padding-x, padding-y, or font-size

👉 Box field sizes are linked to Button sizes so they align nicely when placed in row.

Example:

Check Fields

Options shared by checkable form controls. This includes CheckboxField, Radio, and Toggle.

Custom PropertyDescription
--rui-FormField--check__input__sizeSize of check inputs
--rui-FormField--check__input__border-widthBorder width of check inputs
--rui-FormField--check__input--focus__box-shadowBox shadow to highlight focused inputs
--rui-FormField--check__tap-target-sizeMinimum tap target size

Interaction states:

Custom PropertyDescription
--rui-FormField--check--default__border-colorBorder color of unchecked inputs
--rui-FormField--check--default__check-background-colorBackground color of unchecked inputs
--rui-FormField--check--checked__border-colorBorder color of checked inputs
--rui-FormField--check--checked__check-background-colorBackground color of checked inputs
--rui-FormField--check--disabled__border-colorBorder color of disabled unchecked inputs
--rui-FormField--check--disabled__check-background-colorBackground color of disabled unchecked inputs
--rui-FormField--check--checked-disabled__border-colorBorder color of disabled checked inputs
--rui-FormField--check--checked-disabled__check-background-colorBackground color of disabled checked inputs

Example:

Validation States

Theming options for validation states are shared by all form components. Naming convention looks as follows:

--rui-FormField--<VALIDATION STATE>--<INTERACTION STATE>__<PROPERTY>

Where:

  • <VALIDATION STATE> is one of invalid, valid, or warning
  • <INTERACTION STATE> is one of default, checked, disabled, or checked-disabled
  • <PROPERTY> is one of color, border-color, background, check-background-color, box-shadow, or surrounding-text-color

Not all properties are used by all components, this varies from component to component. Also, hover interaction state is unavailable for validation states everywhere — default state appearance is retained on hovering. For box fields, focus state for validation states is inherited from default form field appearance (i.e. as if no validation state was set).

Example:

Disabled State

By default, all disabled form fields are semi-transparent and change mouse cursor on hover so users know the fields cannot be used.

Custom PropertyDescription
--rui-FormField--disabled__cursorCursor to show on hovering disabled form fields
--rui-FormField--disabled__opacityOpacity of disabled form fields (inc. label and help text)

Should your design require custom styling of disabled fields, individual field types and validation states can be fine-tuned by several theming options available. All you need is to define all necessary custom properties following the naming conventions documented in previous sections (for simplicity, the properties do not exist in the default theme, we only use transparency to mark disabled fields by default). Namely, you will be interested in disabled and checked-disabled interaction states and properties that are available for styling of these states.

Example: