Skip to content

color

color fields provides the end user with a color picker interface. They also validate submitted values using the TinyColor utility. Colors are saved as strings in 8 digit hex code, or #rrggbbaa, format.

Module field definition

javascript
// Configuring the `themeColor` field in a module's `fields.add` subsection:
themeColor: {
  type: 'color',
  label: 'Theme color'
}

Settings

Required

PropertyTypeDefaultDescription
labelStringn/aSets the visible label for the field in the UI
typeStringn/aSpecifies the field type (color for this type)

Optional

PropertyTypeDefaultDescription
defStringn/aThe default value for the field
helpStringn/aHelp text for the content editor
htmlHelpStringn/aHelp text with support for HTML markup
ifObject{}Conditions to meet before the field is active. See the guide for details.
requiredIfObject{}Conditions to meet before the field is required. See the guide for details.
hiddenBooleanfalseIf true, the field is hidden
requiredBooleanfalseIf true, the field is mandatory
readOnlyBooleanfalseIf true, prevents the user from editing the field value
optionsObjectn/aAn object containing color picker configuration. See below.

options

Color fields have additional settings configured in an options object:

format

The color string format saved to the database. Possible options are:

  • rgb
  • prgb
  • hex6
  • hex3
  • hex8
  • hsl
  • hsv

The default value is hex8.

javascript
backgroundColor: {
  type: 'color',
  label: 'Background color',
  options: {
    format: 'rgb'
  }
}

pickerOptions

The color picker interface can be configured to present editors with different selection options. The configuration should go in the options property as pickerOptions. The picker options are below.

presetColors
  • Type: Array

An array of color values, used as swatches.

  • Default Value:
javascript
[
  '#D0021B', '#F5A623', '#F8E71C', '#8B572A', '#7ED321',
  '#417505', '#BD10E0', '#9013FE', '#4A90E2', '#50E3C2',
  '#B8E986', '#000000', '#4A4A4A', '#9B9B9B', '#FFFFFF'
]
  • Usage
javascript
backgroundColor: {
  type: 'color',
  label: 'Background color',
  options: {
    pickerOptions: {
      presetColors: ['#ea433a', '#cc9300', '#b327bf', '#66f', '#00bf9a']
    }
  }
}
disableAlpha
  • Type: Boolean

Control alpha transparency with a range input.

Default value

javascript
false
disableFields
  • Type: Boolean

Control color value with string inputs (Hex & RGBA).

Default value

javascript
false

Use in templates

nunjucks
<button style="background-color: {{ data.piece.themeColor or '#639' }}">
  Enhance
</button>