Color Filters

Color filters let you manipulate color values directly in your templates. You can lighten, darken, saturate, or desaturate a color, mix two colors together, or calculate whether a combination provides sufficient contrast for readability. These filters work best inside {% style %} blocks, where section settings provide a base color and your template generates a complete palette from that single value.

All color filters take CSS color values as input. You can use hex codes like #ff0000, RGB like rgb(255, 0, 0), or HSL like hsl(0, 100%, 50%).

Making colors lighter or darker

color_lighten

Make a color lighter. Pass a number from 0 to 100:

{{ '#336699' | color_lighten: 20 }}

Output: #5c85ad

A higher percentage produces a progressively lighter result. Zero leaves the color unchanged, while 100 produces pure white.

color_darken

Make a color darker. Works the same way as lighten, but in the other direction:

{{ '#336699' | color_darken: 20 }}

Output: #1f3d5c

color_saturate

Make a color more bold and vivid:

{{ '#336699' | color_saturate: 30 }}

A value of 100 gives the most vivid form of that color.

color_desaturate

Make a color more dull and gray:

{{ '#336699' | color_desaturate: 30 }}

At the far end, the color becomes a flat gray tone.

color_modify

Change one part of a color by name. Pass the part name and a new value:

{{ '#336699' | color_modify: 'alpha', 0.5 }}

Output: rgba(51, 102, 153, 0.5)

You can change red, green, blue, hue, lightness, or alpha. This is the most fine-grained way to tweak a color.

Mixing colors

color_mix

Blend two colors into one. The last number sets how much of the first color to use:

{{ '#ff0000' | color_mix: '#0000ff', 50 }}

Output: #800080 (a mix of red and blue in equal parts)

A weight of 75 means 75% red and 25% blue. This is especially useful for generating intermediate tones between two brand colors.

Changing the format

color_to_rgb

Turn any color into its RGB form:

{{ '#336699' | color_to_rgb }}

Output: rgb(51, 102, 153)

color_to_hsl

Turn any color into its HSL form:

{{ '#336699' | color_to_hsl }}

Output: hsl(210, 50%, 40%)

color_to_hex

Turn any color into a hex code:

{{ 'rgb(51, 102, 153)' | color_to_hex }}

Output: #336699

These conversion filters are useful when you need a specific representation for CSS custom properties or for passing to other color filters.

Reading parts of a color

color_extract

Pull one part out of a color as a number:

{{ '#336699' | color_extract: 'red' }}

Output: 51

You can read red, green, blue, hue, lightness, or alpha. This is handy for making choices based on how light or dark a color is:

{% assign light = section.settings.bg_color | color_extract: 'lightness' %}
{% if light > 50 %}
  {% assign text_color = '#000000' %}
{% else %}
  {% assign text_color = '#ffffff' %}
{% endif %}

Checking contrast

These filters help you make sure text is easy to read on a colored background.

color_brightness

Get how bright a color looks, as a number from 0 to 255:

{{ '#336699' | color_brightness }}

Output: 89.16

Below 128 is dark. Above 128 is light. Use this to pick white or black text.

color_contrast

Get the contrast ratio between two colors:

{{ '#336699' | color_contrast: '#ffffff' }}

Output: 5.43

The WCAG rule says you need at least 4.5 for normal text and 3.0 for large text. This filter tells you if your pair of colors meets that bar.

brightness_difference

Get the gap in brightness between two colors:

{{ '#336699' | brightness_difference: '#ffffff' }}

color_difference

Get the total gap across all color channels between two colors:

{{ '#336699' | color_difference: '#ffffff' }}

A higher number means the two colors are more distinct from each other.

Putting it all together

This pattern reads a color from section settings, picks a text color that will be easy to read, and builds hover and link styles from the same base value:

{% assign bg = section.settings.background_color %}
{% assign ratio = bg | color_contrast: '#ffffff' %}

{% if ratio > 4.5 %}
  {% assign text = '#ffffff' %}
{% else %}
  {% assign text = '#000000' %}
{% endif %}

{% style %}
  .section-{{ section.id }} {
    background-color: {{ bg }};
    color: {{ text }};
  }
  .section-{{ section.id }} a {
    color: {{ bg | color_lighten: 30 }};
  }
  .section-{{ section.id }}:hover {
    background-color: {{ bg | color_darken: 10 }};
  }
{% endstyle %}

One color from the merchant, and your theme does the rest.