PHPackages                             percipioglobal/craft-colour-swatches - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. percipioglobal/craft-colour-swatches

Abandoned → [craftpulse/craft-colour-swatches](/?search=craftpulse%2Fcraft-colour-swatches)Craft-plugin

percipioglobal/craft-colour-swatches
====================================

Let clients choose from a predefined set of colours and utilise associated colour codes and class names in your templates.

4.3.0(3y ago)35190.2k↑89.6%22[11 issues](https://github.com/percipioglobal/craft-colour-swatches/issues)[3 PRs](https://github.com/percipioglobal/craft-colour-swatches/pulls)7MITPHPPHP ^8.0.2

Since Jan 14Pushed 6mo ago2 watchersCompare

[ Source](https://github.com/percipioglobal/craft-colour-swatches)[ Packagist](https://packagist.org/packages/percipioglobal/craft-colour-swatches)[ RSS](/packages/percipioglobal-craft-colour-swatches/feed)WikiDiscussions v5 Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (72)Used By (7)

[![colour-swatches-banner-light](./resources/img/banner.jpg)](./resources/img/banner.jpg)

Create custom colour palettes with flexibility & control.

Colour Swatches plugin for Craft CMS 4+
=======================================

[](#colour-swatches-plugin-for-craft-cms-4)

Instead of providing a user a full color picker, Colour Swatches is a configurable a fieldtype that gives an admin the ability to provide a selection of colours for a user to choose from. This allows you to create branded colour palettes with a bank of classnames ready to use in your templates.

[![Screenshot](./resources/img/colour-swatches-1.png)](./resources/img/colour-swatches-1.png)

Requirements
------------

[](#requirements)

This plugin requires Craft CMS 4.0.0 or later.

Installation
------------

[](#installation)

To install the plugin, follow these instructions.

1. Open your terminal and go to your Craft project:

    ```
     cd /path/to/project

    ```
2. Then tell Composer to load the plugin:

    ```
     composer require craftpulse/craft-colour-swatches

    ```
3. In the Control Panel, go to Settings → Plugins and click the "Install" button for Colour Swatches.

Configuring Colour Swatches
---------------------------

[](#configuring-colour-swatches)

### Using the field settings

[](#using-the-field-settings)

Create a Colour Swatches field and provide label and hex value options. Multiple colours are possible by seperating them with a comma.

[![Screenshot](./resources/img/colour-swatches-3.png)](./resources/img/colour-swatches-3.png)

#### When using Colour Swatches with the field settings

[](#when-using-colour-swatches-with-the-field-settings)

You can access both the label and color in your template. By default, the label will display:

```
    {{ fieldName }}
    {{ fieldName.label }}
    {{ fieldName.color }}
```

```
    {% for color in fieldName.color %}
        {{ color.color }}
    {% endfor %}
```

If you want more granular control with your colour palettes, use the configuration file option below.

### Using the config file

[](#using-the-config-file)

You can use a `config/colour-swatches.php` config file file to predefine the possible colours, define different palettes and add lables, classnames or other attributes to your colours.

Take a look at the [config file](https://github.com/craftpulse/craft-colour-swatches/blob/v5/src/config.php) in this repo for an example.

```
return [

    // Custom  palettes, fixed options [label, default (boolean), colour (array(colour, customOptions)) ]
    'palettes' => [
        'Tailwind' => [  // custom label (required)
            [
                'label'   => 'Red', // custom label (required)
                'default' => true,  // default could be true/false (option is required)
                'color'   =>  [
                    [
                        'color'             => '#ef4444',               // the colour shown in the fieldtype (required)
                        'background'        => 'bg-red-500',            // optional / custom attribute
                        'backgroundHover'   => 'hover:bg-red-700',      // optional / custom attribute
                        'text'              => 'text-white',            // optional / custom attribute
                        'textHover'         => 'hover:text-zinc-200'    // optional / custom attribute
                    ]
                ]
            ],
            [
                'label'   => 'Amber',
                'default' => false,
                'color'   =>  [
                    [
                        'color'             => '#f59e0b',
                        'background'        => 'bg-amber-500',
                        'backgroundHover'   => 'hover:bg-amber-700',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ]
                ]
            ],
            [
                'label'   => 'Green',
                'default' => false,
                'color'   =>  [
                    [
                        'color'             => '#22c55e',
                        'background'        => 'bg-green-500',
                        'backgroundHover'   => 'hover:bg-green-700',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ]
                ]
            ],
            [
                'label'   => 'Blue',
                'default' => false,
                'color'   =>  [
                    [
                        'color'             => '#3b82f6',
                        'background'        => 'bg-blue-500',
                        'backgroundHover'   => 'hover:bg-blue-700',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ]
                ]
            ],
            [
                'label'   => 'Purple',
                'default' => false,
                'color'   =>  [
                    [
                        'color'             => '#a855f7',
                        'background'        => 'bg-purple-500',
                        'backgroundHover'   => 'hover:bg-purple-700',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ]
                ]
            ],
            [
                'label'   => 'Yellow/Emerald',
                'default' => false,
                'color'   =>  [
                    [
                        'color'             => '#eab308',
                        'background'        => 'bg-yellow-500',
                        'backgroundHover'   => 'hover:bg-yellow-700',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ],
                    [
                        'color'             => '#059669',
                        'background'        => 'bg-emerald-600',
                        'backgroundHover'   => 'hover:bg-emerald-800',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ]
                ]
            ],
            [
                'label'   => 'Red/Amber',
                'default' => false,
                'color'   =>  [
                    [
                        'color'             => '#a855f7',
                        'background'        => 'bg-red-500',
                        'backgroundHover'   => 'hover:bg-red-700',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ],
                    [
                        'color'             => '#f59e0b',
                        'background'        => 'bg-amber-500',
                        'backgroundHover'   => 'hover:bg-amber-700',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ]
                ]
            ],
            [
                'label'   => 'Sky/Rose',
                'default' => false,
                'color'   =>  [
                    [
                        'color'             => '#0ea5e9',
                        'background'        => 'bg-sky-500',
                        'backgroundHover'   => 'hover:bg-sky-700',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ],
                    [
                        'color'             => '#e11d48',
                        'background'        => 'bg-rose-600',
                        'backgroundHover'   => 'hover:bg-rose-800',
                        'text'              => 'text-white',
                        'textHover'         => 'hover:text-zinc-200'
                    ]
                ]
            ],
        ]
    ]

];
```

In your field settings you can then have the possibility to have it use the predefined colours.

[![Screenshot](./resources/img/colour-swatches-2.png)](./resources/img/colour-swatches-2.png)

#### Making changes to your config file

[](#making-changes-to-your-config-file)

If have entries using Colour Swatches and you make changes to your config file, you will need to resave your entries for new information from your config file to be pulled into your entry data.

From the command line you can run Crafts `./craft resave/entries` and your entries will be populated with any changes to from your `colour-swatches.php` config file.

**Note:** As of version 5.2.0, Colour Swatches uses a silent handle system for stability. When you first save entries, a handle is automatically generated from the label (e.g., "Red" becomes "red"). This handle is used to match colours even if you change the label later.

#### Using Colour Swatches

[](#using-colour-swatches)

You can access both the label and color in your template. By default, the label will display:

```
    {{ fieldName }}
    {{ fieldName.label }}
    {{ fieldName.color }}
    {{ fieldName.customAttribute }}
```

If you're using multiple colours you will need to loop through your color array

```
    {% for field in fieldName.color %}
        {{ field.color }}
        {{ field.customAttribute }}
    {% endfor %}
```

#### Using Collections

[](#using-collections)

The `collection()` method (added in v5.1.0) returns a recursive Laravel collection for easier manipulation:

```
{# Get all hex values as an array #}
{% set hexValues = fieldName.collection().pluck('color').all() %}

{# Filter colors by a custom attribute #}
{% set darkColors = fieldName.collection()
    .filter(c => c.background is defined and 'dark' in c.background) %}

{# Map to custom format #}
{% set cssVars = fieldName.collection()
    .map(c => '--color: ' ~ c.color ~ ';')
    .implode(' ') %}

{# Chain multiple operations #}
{% set backgrounds = fieldName.collection()
    .pluck('background')
    .filter()
    .unique()
    .all()
%}

{# Get count of colors #}
{% set colorCount = fieldName.collection().count() %}

{# Create CSS gradient from colors #}
{% set gradient = 'linear-gradient(' ~ fieldName.collection().pluck('color').implode(', ') ~ ')' %}
Gradient background
```

Changing Labels
---------------

[](#changing-labels)

By default, colour options are identified by their labels. The plugin now uses a silent handle system to maintain stability.

### How Handles Work

[](#how-handles-work)

When an entry is saved, a handle is automatically generated from the label and stored in the database:

- "Red" → handle: "red"
- "Primary Red" → handle: "primary-red"
- "Sky Blue" → handle: "sky-blue"

**This handle is stored silently and never exposed in your templates.**

### Safe Label Changes

[](#safe-label-changes)

**Option 1: Add explicit handles (Recommended)**

Add a `handle` field to your config before changing labels:

```
'palettes' => [
    'Tailwind' => [
        [
            'handle' => 'red',        // Add this once - keeps it stable
            'label' => 'Red',         // Can be changed freely after handle is set
            'color' => [['color' => '#ef4444']]
        ]
    ]
]
```

**Workflow:**

1. Add `handle` to your config entries
2. Run `./craft resave/entries` once to store handles
3. Now you can change `label` values without breaking existing entries

**Option 2: Without explicit handles**

If you don't add explicit handles, the system auto-generates them from labels. To change a label:

1. Change the label in your config
2. Run `./craft resave/entries` to update all entries

### Handle Priority

[](#handle-priority)

The system uses this priority for handles:

1. **Explicit handle in config** → Always used if present (allows intentional handle changes)
2. **Existing handle in database** → Preserved for stability
3. **Auto-generated from label** → Created on first save

This means you have full control: use auto-generation for simplicity, or add explicit handles when you need guaranteed stability.

### GraphQL

[](#graphql)

Colour Swatches comes with GraphQL support you can build a query as follows:

```
fieldName {
        label
        class
        color
      }

```

which will give you the following result if you use the config file:

```
"fieldName": {
          "label": "Black/White",
          "class": "",
          "color": [
            "{\"color\":\"#000000\",\"background\":\"bg-black\"}",
            "{\"color\":\"#ffffff\",\"text\":\"text-white\"}"
          ]
        },

```

or in case of a single value added through the settings you will see:

```
"fieldName": {
          "label": "Black",
          "class": "",
          "color": [
            "#000000"
          ]
        },

```

Brought to you by [Craft Pulse](https://github.com/craftpulse)

###  Health Score

53

—

FairBetter than 97% of packages

Maintenance41

Moderate activity, may be stable

Popularity44

Moderate usage in the ecosystem

Community28

Small or concentrated contributor base

Maturity83

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 55.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~38 days

Recently: every ~125 days

Total

56

Last Release

904d ago

Major Versions

1.5.1 → 4.0.0-beta.12022-04-20

1.5.2 → 4.0.0-beta.22022-05-02

1.6.0 → 4.2.02022-07-08

1.7.0 → v3.x-dev2022-07-12

v3.x-dev → 4.2.12022-11-09

### Community

Maintainers

![](https://www.gravatar.com/avatar/9d008342ae63e14503bcee1a019015893578554e4d2cc567a41d87725d870c92?d=identicon)[percipio](/maintainers/percipio)

---

Top Contributors

[![michtio](https://avatars.githubusercontent.com/u/5818021?v=4)](https://github.com/michtio "michtio (67 commits)")[![cookie10codes](https://avatars.githubusercontent.com/u/20947573?v=4)](https://github.com/cookie10codes "cookie10codes (40 commits)")[![chasegiunta](https://avatars.githubusercontent.com/u/1377169?v=4)](https://github.com/chasegiunta "chasegiunta (3 commits)")[![ammannbe](https://avatars.githubusercontent.com/u/26964239?v=4)](https://github.com/ammannbe "ammannbe (2 commits)")[![pixelmachine](https://avatars.githubusercontent.com/u/1082223?v=4)](https://github.com/pixelmachine "pixelmachine (2 commits)")[![craftedsystems](https://avatars.githubusercontent.com/u/26137287?v=4)](https://github.com/craftedsystems "craftedsystems (2 commits)")[![markmiddleton](https://avatars.githubusercontent.com/u/2645384?v=4)](https://github.com/markmiddleton "markmiddleton (2 commits)")[![timeverts](https://avatars.githubusercontent.com/u/15150632?v=4)](https://github.com/timeverts "timeverts (1 commits)")[![benface](https://avatars.githubusercontent.com/u/1059139?v=4)](https://github.com/benface "benface (1 commits)")[![engram-design](https://avatars.githubusercontent.com/u/1221575?v=4)](https://github.com/engram-design "engram-design (1 commits)")

---

Tags

cmsCraftcraftcmscraft-plugincolorscolourscolour-swatchescolor-swatchesswatches

### Embed Badge

![Health badge](/badges/percipioglobal-craft-colour-swatches/health.svg)

```
[![Health](https://phpackages.com/badges/percipioglobal-craft-colour-swatches/health.svg)](https://phpackages.com/packages/percipioglobal-craft-colour-swatches)
```

###  Alternatives

[craftpulse/craft-colour-swatches

Let clients choose from a predefined set of colours and utilise associated colour codes and class names in your templates.

3530.8k2](/packages/craftpulse-craft-colour-swatches)[nystudio107/craft-seomatic

SEOmatic facilitates modern SEO best practices & implementation for Craft CMS 5. It is a turnkey SEO system that is comprehensive, powerful, and flexible.

1741.4M46](/packages/nystudio107-craft-seomatic)[doublesecretagency/craft-matrixcolors

Identify your matrix blocks by giving each type a different color.

4518.3k](/packages/doublesecretagency-craft-matrixcolors)[presseddigital/colorit

A slick color picker fieldtype plugin for the Craft CMS 3 control panel.

2132.1k](/packages/presseddigital-colorit)[verbb/image-resizer

Resize assets when they are uploaded.

127269.1k7](/packages/verbb-image-resizer)[verbb/tablemaker

Create customizable and user-defined table fields.

40168.8k1](/packages/verbb-tablemaker)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)