PHPackages                             sylvainjule/colorextractor - 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. [Image & Media](/categories/media)
4. /
5. sylvainjule/colorextractor

ActiveKirby-plugin[Image & Media](/categories/media)

sylvainjule/colorextractor
==========================

Extract dominant / average color from any image.

2.1.0(9mo ago)423.4k↓25%81MITPHP

Since Dec 12Pushed 9mo ago4 watchersCompare

[ Source](https://github.com/sylvainjule/kirby-colorextractor)[ Packagist](https://packagist.org/packages/sylvainjule/colorextractor)[ RSS](/packages/sylvainjule-colorextractor/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (1)Versions (12)Used By (1)

Kirby – Color extractor
=======================

[](#kirby--color-extractor)

[![colorextractor](https://user-images.githubusercontent.com/14079751/45950127-c73c0d00-bffe-11e8-8e10-eef90185f624.jpg)](https://user-images.githubusercontent.com/14079751/45950127-c73c0d00-bffe-11e8-8e10-eef90185f624.jpg)

This plugins extracts a dominant / average color of any image and stores it in the file's metadata as a HEX value. Optionally, it can also generate a color palette to be used in combination with the `color` field.

Overview
--------

[](#overview)

> This plugin is completely free and published under the MIT license. However, if you are using it in a commercial project and want to help me keep up with maintenance, you can consider [making a donation of your choice](https://www.paypal.me/sylvainjl).

- [1. Installation](#1-installation)
- [2. Default usage](#2-default-usage)
    - [2.1. Hook](#21-hook)
    - [2.2. Panel button](#22-panel-button)
- [3. Default options](#3-default-options)
    - [3.1. Extraction mode](#31-extraction-mode)
    - [3.2. Transparency handling](#32-transparency-handling)
- [4. Displaying and using the color](#4-displaying-and-using-the-color)
    - [4.1. If a single color is extracted](#41-if-a-single-color-is-extracted)
    - [4.2. If both colors are extracted](#42-if-both-colors-are-extracted)
- [5. Palette usage](#5-palette-usage)
    - [5.1. Hook](#51-hook)
    - [5.2. Field method](#52-field-method)
- [6. License](#6-license)
- [7. Credits](#7-credits)

1. Installation
---------------

[](#1-installation)

> Compatible with Kirby 5 (latest release) as well as Kirby 3 and 4 (maintained / tested up to v2.0.0 of this plugin).

Download and copy this repository to `/site/plugins/colorextractor`

Alternatively, you can install it with composer: `composer require sylvainjule/colorextractor`

2. Default usage
----------------

[](#2-default-usage)

It can be used in two ways :

#### 2.1. Hook

[](#21-hook)

Once installed within the `plugins` folder, it will automatically start extracting colors for any image uploaded or replaced in the panel.

#### 2.2. Panel button

[](#22-panel-button)

If you happen to upload files manually, from frontend or any other way while not trigerring the hooks, custom [janitor](https://github.com/bnomei/kirby3-janitor) jobs are also available to catch up with all the images of a website without an associated color.

You'll first need to install the janitor plugin and the Kirby CLI:

```
composer require getkirby/cli bnomei/kirby3-janitor
```

Then use the jobs in your blueprints:

```
colorextractor:
    type: janitor
    label: Extract missing colors
    progress: 'Processing…'
    command: janitor:job --key sylvainjule.colorextractor.jobs.extractColors
```

The `extractColors` job will only extract the **missing colors**. If you want to force a re-extraction of existing colors, use the `forceExtractColors` job instead.

3. Default options
------------------

[](#3-default-options)

#### 3.1. Extraction mode

[](#31-extraction-mode)

By default, the plugin tends to extract the most dominant / vibrant color of the image. Sometimes though, it can be handy to extract an average one based on an approximation of the whole color palette. When set to `average`, this options shrinks the image to a 1x1 pixel thumb, then grab the color the image processor chose as the average one. You'll find some examples [here](https://github.com/sylvainjule/kirby3-colorextractor/blob/master/docs/examples.md).

You can also set it to `both`, if you want both colors to be extracted and pick from them later from your templates (see the [`plugin's methods`](#42-if-both-colors-are-extracted))

Available options are `dominant | average | both`. Default is `dominant`.

```
// config/config.php
return array(
  'sylvainjule.colorextractor.mode' => 'dominant',
);
```

#### 3.2. Transparency handling

[](#32-transparency-handling)

The plugin needs to know how to handle colors with alpha value greater than zero, and what color to fallback to when transparency is detected.

Default is `#ffffff`

```
// config/config.php
return array(
  'sylvainjule.colorextractor.fallbackColor' => '#000000',
);
```

4. Displaying and using the color
---------------------------------

[](#4-displaying-and-using-the-color)

#### 4.1. If a single color is extracted

[](#41-if-a-single-color-is-extracted)

In case you have chosen either `dominant` (default) or `average` extraction mode, you can access it directly from your template under the `color` fieldname:

```
$image->color();
```

The plugin works well combined with [@hananils's color picker](https://github.com/hananils/kirby-colors), which might come handy to preview and adjust the detected color.

```
# Place this inside your file blueprint
fields:
  color:
    type: colors
```

#### 4.2. If both colors are extracted

[](#42-if-both-colors-are-extracted)

If you have chosen to extract and store both colors, the color field will store both HEX values delimited by a comma. The plugin provides a file method to get a specific color from there:

```
$image->color()->dominantColor();
$image->color()->averageColor();
```

5. Palette usage
----------------

[](#5-palette-usage)

[![palette](https://private-user-images.githubusercontent.com/14079751/475276209-1a0f13a5-49f5-4db6-b514-d91b8619d9d8.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQ3NDkwODIsIm5iZiI6MTc3NDc0ODc4MiwicGF0aCI6Ii8xNDA3OTc1MS80NzUyNzYyMDktMWEwZjEzYTUtNDlmNS00ZGI2LWI1MTQtZDkxYjg2MTlkOWQ4LmpwZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAzMjklMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMzI5VDAxNDYyMlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTAxMjQ4NDM0ZTQ5OWMzZWY1MDk2MjIxODg3ZTA4Y2NkMDU1YTFlZjUyYmZmYjY5M2Q5YjUwMjFkYTNiOTRkYzkmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.YVrtFBpvpERQe0Wy2oDrdQAtjj5E3qlkcrdPyXoI6Bo)](https://private-user-images.githubusercontent.com/14079751/475276209-1a0f13a5-49f5-4db6-b514-d91b8619d9d8.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQ3NDkwODIsIm5iZiI6MTc3NDc0ODc4MiwicGF0aCI6Ii8xNDA3OTc1MS80NzUyNzYyMDktMWEwZjEzYTUtNDlmNS00ZGI2LWI1MTQtZDkxYjg2MTlkOWQ4LmpwZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAzMjklMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMzI5VDAxNDYyMlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTAxMjQ4NDM0ZTQ5OWMzZWY1MDk2MjIxODg3ZTA4Y2NkMDU1YTFlZjUyYmZmYjY5M2Q5YjUwMjFkYTNiOTRkYzkmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.YVrtFBpvpERQe0Wy2oDrdQAtjj5E3qlkcrdPyXoI6Bo)

You have two options to generate the palette:

#### 5.1. Hook

[](#51-hook)

You can generate a palette for any image uploaded or replaced in the panel. In order to to so, you need to set the `palette.hook` option to `true` (default if `false`).

Additionally, you can:

- The number of colors to be extracted with the `palette.limit` option (default is `10`)
- If the palette generation is to be restricted to specific file templates with the `palette.template` option (default is `null`: a palette will be generated for any image with any template if the palette hook is active. `String | Array`).

```
# default values
'sylvainjule.colorextractor.palette' => [
    'hook'     => false,
    'limit'    => 10,
    'template' => null
],

# example values
'sylvainjule.colorextractor.palette' => [
    'hook'     => true,
    'limit'    => 12,
    'template' => ['template-1', 'template-2'],
    // 'template' => 'template-1', also works
],
```

The palette will be stored in the file .txt with the fieldname: `palette`. The plugin provides a dedicated field methods to use is, see below.

If you only need this plugin to extract palettes, you can also disable the default average / dominant color extraction hook with the `default.hook` option (default is `true`):

```
'sylvainjule.colorextractor.default.hook' => false,
```

#### 5.2. Field method

[](#52-field-method)

If you don't want any hook running, you can also choose not to activate the hook but use the `->getPalette()` method.

- If the `palette` exists (= is not empty), the method will return it as an array
- If the `palette` doesn't exist, it will process the image, generate and save it, then return it as an array.

You can use is to populate the [`color` field options](https://getkirby.com/docs/reference/panel/fields/color#options), for example:

```
colorPicker:
  type: color
  mode: options
  options:
    type: query
    query: page.filePicker.toFile.getPalette
    # query: page.files.first.getPalette
    # query: page.files.first.palette.yaml → also works if the palette has already been generated
    # ...
```

6. License
----------

[](#6-license)

MIT

7. Credits
----------

[](#7-credits)

- K2 Field by [@iandoe](https://github.com/iandoe/kirby-dominant-color/blob/master/README.md)
- Color extracting process by [@thephpleague](https://github.com/thephpleague/color-extractor)

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance57

Moderate activity, may be stable

Popularity35

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 95% 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 ~242 days

Recently: every ~333 days

Total

11

Last Release

286d ago

Major Versions

1.0.8 → 2.0.02024-03-10

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/14079751?v=4)[Sylvain Julé](/maintainers/sylvainjule)[@sylvainjule](https://github.com/sylvainjule)

---

Top Contributors

[![sylvainjule](https://avatars.githubusercontent.com/u/14079751?v=4)](https://github.com/sylvainjule "sylvainjule (76 commits)")[![moritzebeling](https://avatars.githubusercontent.com/u/39742729?v=4)](https://github.com/moritzebeling "moritzebeling (2 commits)")[![johannschopplich](https://avatars.githubusercontent.com/u/27850750?v=4)](https://github.com/johannschopplich "johannschopplich (1 commits)")[![simonknebl](https://avatars.githubusercontent.com/u/7932637?v=4)](https://github.com/simonknebl "simonknebl (1 commits)")

---

Tags

backgroundcolorextractorimagekirbykirby-pluginpalette

### Embed Badge

![Health badge](/badges/sylvainjule-colorextractor/health.svg)

```
[![Health](https://phpackages.com/badges/sylvainjule-colorextractor/health.svg)](https://phpackages.com/packages/sylvainjule-colorextractor)
```

###  Alternatives

[flokosiol/focus

Better image cropping for Kirby CMS

18265.1k](/packages/flokosiol-focus)[sylvainjule/annotator

Place pins / define zones on an image synced with a structure field

10915.2k](/packages/sylvainjule-annotator)[tobimori/kirby-thumbhash

Kirby Image placeholders with the smarter ThumbHash integration

378.1k1](/packages/tobimori-kirby-thumbhash)[sylvainjule/imageradio

Add illustrations to Kirby's radio buttons

5916.8k](/packages/sylvainjule-imageradio)[timnarr/kirby-imagex

Modern images for Kirby CMS – This plugin helps you orchestrate modern, responsive and performant images in Kirby

797.5k1](/packages/timnarr-kirby-imagex)[felixhaeberle/kirby3-webp

Kirby 3 CMS plugin for converting JPG, JPEG and PNG into much smaller WEBP – speed up your website!

397.5k](/packages/felixhaeberle-kirby3-webp)

PHPackages © 2026

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