Colorguide for Magento 2

Sell configurable products with virtually unlimited option combinations — brand, colour, and size — without the performance hit of native Magento custom options or a simple product for every colour and size. Colorguide keeps brand, colour, and price data in three lightweight custom tables and presents a guided, step-by-step selection wizard on the storefront.

🧭

Guided Selection Wizard

A four-step flow — Colour Palette → Brand → Colour → Container Size — narrows choices at each step instead of one long swatch list.

🗂️

Palette Families

Group colours into families (Neutral, Red, Green, Blue, and more) so shoppers browse a handful of tiles instead of scrolling every colour.

⚡

Lightweight Data Model

Brand, colour, and price data live in three dedicated tables, not per-product custom options — thousands of combinations without catalog bloat.

🖼️

Hex or Image Swatches

Each colour renders as a flat hex-colour swatch or an uploaded reference image, whichever fits the product.

🛒

Brand & Colour on the Order

The selected brand and colour are recorded as visible options on the cart line item, order, and invoice.

🧩

Pairs With Configurable Products

Colorguide handles brand/colour; Magento's native swatch renderer continues to drive the configurable size or container axis.

💡

Colorguide is designed for products where colour is a surface finish — paint, stain, upholstery fabric, laminate — rather than a strict Magento configurable axis. Size (or container volume) stays a real configurable attribute with its own child products and prices; colour and brand are layered on top without multiplying SKUs.

Requirements

Dependency	Version	Notes
Magento Open Source / Adobe Commerce	2.4.x
PHP	8.1+	Required by Magento framework
magento/framework	>=103.0	Installed via Composer
Backend, Sales, Quote, Checkout, Cms, Catalog modules	*	Standard Magento modules; present on any default install

⚠️

The product Colorguide is attached to must be a configurable product whose configurable option is a swatch-type attribute (Text Swatch or Visual Swatch) — Size or Container Size, for example. See Product Setup.

Installation

Install via Composer after configuring your credentials. See your dashboard for your license key.

1

Add the repository to your project (one-time)

composer config repositories.ayasoftware composer https://www.ayasoftware.com/repo

2

Add your credentials to auth.json (one-time)

composer config --global http-basic.www.ayasoftware.com your@email.com YOUR_LICENSE_KEY

Your license key is available in the Ayasoftware dashboard.

3

Require and enable the extension

composer require ayasoftware/module-colorguide:^1.2
bin/magento module:enable Ayasoftware_Colorguide
bin/magento setup:upgrade

4

Production mode only

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

💡

setup:upgrade creates three tables (ayasoftware_colorguide_brand, ayasoftware_colorguide_colours_menu, ayasoftware_colorguide_price_menu) and adds the Paint Brands product attribute automatically to every attribute set — no manual attribute-set edits needed. Upgrading from a version earlier than 1.2.0 also adds the colourfamily column used by the palette wizard; existing colour rows are left with an empty family until you assign one in the admin grid. Upgrading from a version earlier than 1.2.1 additionally creates the Container Size attribute (see Product Setup) pre-seeded with two starter options.

Verify the installation

bin/magento module:status Ayasoftware_Colorguide

Then confirm Stores → Color Guide appears in the admin menu, with Manage Paint Brands, Manage Paint Brands Prices, and Manage Paint Colors underneath it.

Data Model & Admin Grids

Colorguide stores brand, colour, and price data in three dedicated tables instead of Magento custom options, so a catalog can offer thousands of brand/colour/size combinations without per-product option bloat. Each table has its own admin grid under Stores → Color Guide.

Admin grid	Table	Key fields
Manage Paint Brands /admin/colorguide/brand/index	`ayasoftware_colorguide_brand`	`id`, `paintbrand` (brand name)
Manage Paint Colors /admin/colorguide/color/index	`ayasoftware_colorguide_colours_menu`	`id`, `paintbrand` (Brand ID), `colourname`, `colourfamily`, `hexcolour`, `hexcolourimage`
Manage Paint Brands Prices /admin/colorguide/price/index	`ayasoftware_colorguide_price_menu`	`id`, `paintbrand` (Brand ID), `size` (Container Size attribute option ID), `price`

⚠️

paintbrand means two different things depending on the table: on the product's Paint Brands attribute it stores the brand name (a string); on the Colour and Price rows it stores the brand's numeric id from the Brand table. Keep this in mind for bulk imports or direct database edits.

Colour Family

Each colour row can optionally be assigned a Colour Family — the group it belongs to on the storefront's first wizard step. Options are fixed: White, Grey, Black, Brown, Neutral, Red, Orange, Yellow, Green, Blue, Purple.

🚫

A colour with no Colour Family assigned is unreachable through the storefront wizard — it never matches a palette tile in step 1, so a customer can never filter down to it. Assign a family to every colour you want customers to find. See Troubleshooting.

Import & Export New in 1.3.0

Instead of entering brands, colours, and prices one row at a time across three separate grids, Stores → Color Guide → Import / Export lets you manage all three from a single CSV file.

Column	Used for
`brand`	Required on every row with data. An unrecognized brand name is created automatically.
`colour_name`	Fill in to add or update a colour on that brand.
`colour_family`	One of the fixed Colour Family values (White, Grey, Black, Brown, Neutral, Red, Orange, Yellow, Green, Blue, Purple).
`hex_colour`	Optional hex value for the swatch, e.g. `#3A6EA5`.
`hex_colour_image`	Optional — the filename of a swatch image already uploaded via the Manage Paint Colors edit form. Import does not upload image files itself.
`container_size`	Fill in together with `price` to add or update a price. Must match an existing option label on the Container Size attribute.
`price`	Numeric price for the brand + container size on this row.

A row can set a colour and a price at the same time, or just one of the two — leave the other set of columns blank. Existing rows are matched by brand + colour name (for colours) or brand + container size (for prices) and updated in place; anything that doesn't match an existing row is added as new. Import never deletes data — remove rows from the grids directly if needed.

1

Download a starting point

Use Download Sample Template for a blank CSV with the right columns and two example rows, or Export Current Data as CSV to pull everything already in your catalog into the same format — handy for bulk-editing existing prices in a spreadsheet before re-uploading.

2

Edit the CSV and upload it

Choose the file and click Import. The container sizes you reference must already exist under Stores → Attributes → Product → Container Size — import does not create new attribute options.

3

Review the results

The page reports how many brands/colours/prices were created or updated, and lists the exact row number and reason for any row that couldn't be applied — for example, an unrecognized container size or an invalid hex colour. Everything else in the file still imports; only the affected rows are skipped.

💡

Because matching is brand + colour name (or brand + size), re-uploading the same file twice is safe — the second run just updates the same rows again instead of creating duplicates.

Product Setup

Colorguide attaches to a single configurable product. Complete these steps in order for a new product:

1

Create a configurable product using the Container Size attribute

Colorguide ships a ready-made Container Size attribute (Text Swatch, attribute code container_size), pre-seeded with two starter options — "1 Gallon (3.78L)" and "5 Gallons (18.9L)". Use Create Configurations with Container Size (or your own swatch-type attribute) as the configurable option, and create one child (simple) product per size, each with its own price and stock.

2

Add or edit Container Size options for your catalog

Go to Stores → Attributes → Product → Container Size to add, remove, or rename options to match what you actually sell.

🚫

The Price grid's Container Size field, and the storefront wizard's final step, both pull their choices directly from this attribute's option list. An attribute with no options renders as an empty dropdown in both places — always confirm it has at least one option before configuring a product.

3

Set the parent product's Paint Brands attribute

On the parent configurable product, open the Paint Brands multiselect (added automatically to every attribute set) and select every brand this product should offer. A product with no brand selected never shows the Colorguide wizard.

4

Add colours for each brand

In Stores → Color Guide → Manage Paint Colors, add one row per colour: brand, colour name, a Colour Family, and either a hex colour or an uploaded swatch image.

5

Add prices (optional)

In Manage Paint Brands Prices, add a row per brand + size if a brand carries a surcharge over the base product price for a given container size. Leave a size/brand combination unset to charge no surcharge.

💡

Repeat steps 3–5 for every configurable product that should use Colorguide — brand and colour data can be reused across as many products as needed once entered.

Storefront Wizard

Once a product has at least one Paint Brand selected, Colorguide replaces the product page's default option layout with a four-step wizard:

Colour Palette — palette-family tiles (Neutral, Red, Green, Blue, …), built from the colour families assigned in the admin grid.
Brand — brands that carry at least one colour in the selected family.
Colour — colours for the selected brand and family, with a live search box.
Container Size — Magento's native swatch selector for the configurable size attribute, relocated into the final step so size is chosen last, after colour.

Quantity and Add to Cart move to the very end of the wizard, after all four steps. Add to Cart is blocked with an inline message until a colour has been selected.

💡

The wizard only appears when hasColorguide() is true — i.e. the product has a Paint Brands value. Products without a brand selected fall back to Magento's default configurable-product option layout.

Cart & Order Data

The selected Colour and Brand are recorded as additional options on the cart line item and carry through to the order and invoice, alongside the native Size option from the configurable attribute:

Option	Source
Size	Native Magento configurable attribute — always present
Colour	Colorguide — shown whenever a colour was selected
Brand	Colorguide — shown whenever a colour was selected 1.2.0+

The same Colour and Brand options are also restored on reorder from an existing order in the admin panel.

Troubleshooting

The wizard doesn't appear at all

Confirm the product has at least one brand selected in its Paint Brands attribute.
Confirm that brand has at least one colour row in Manage Paint Colors.
Flush cache (bin/magento cache:flush) after changing either.

A colour never shows up on the storefront

Its Colour Family field is empty. Every colour needs a family assigned or the wizard can never reach it — see the callout in Data Model.

Add to Cart fails with "You need to choose options for your item"

Confirm the product is a genuine configurable product with the size/container attribute set up via Create Configurations, and that each child product has stock.
If the storefront theme or a custom template repositions the Colorguide markup, make sure it stays inside the Add to Cart <form> — moving it outside the form silently drops the selected size from the submission.

Admin grids (Brands / Colours / Prices) show a fatal error in production mode

This was a compiled-DI compatibility issue fixed in 1.2.0. Update to the latest version and re-run bin/magento setup:di:compile.

Brand isn't shown as a selected option in the cart

Brand-on-cart requires 1.2.0 or later. Earlier versions record Colour only.

Container Size shows as an empty dropdown

The Container Size attribute has no options. Go to Stores → Attributes → Product → Container Size and add at least one option — this affects both the Price grid's Container Size field and the storefront wizard's final step, since both read directly from the attribute's option list.

Grid "Delete" and mass-action "Delete" 404 after upgrading

In production mode, Magento caches the list of valid admin controller actions at compile time. After updating the extension, re-run bin/magento setup:di:compile (see Installation) so new admin actions are recognized.

Import reports "unknown container_size" for a value I can see in the grid

The container_size column must match an existing option label on the Container Size attribute exactly (case-insensitive, but the text otherwise has to match) — go to Stores → Attributes → Product → Container Size, confirm the option's exact label, and update the CSV to match. Import intentionally never creates new attribute options.

Import / Export page isn't in the menu after updating

Import/Export requires 1.3.0 or later, and — like any new admin controller — needs bin/magento setup:di:compile re-run in production mode (see Installation) before the new page and its menu entry are recognized.

Changelog

v1.3.0 August 12, 2026

New

FeatImport/Export page (Stores → Color Guide → Import / Export) — upload a single CSV to create or update paint brands, colours, and prices in one go. Existing rows are matched by brand + colour name (colours) or brand + container size (prices) and updated in place; new combinations are added automatically. Nothing is ever deleted by an import.
FeatExport button downloads all current brand/colour/price data as a CSV in the same format the importer reads, so it can be edited in a spreadsheet and re-uploaded
FeatDownload Sample Template button provides a ready-to-fill starter CSV showing the expected columns

💡

Run bin/magento setup:upgrade and bin/magento setup:di:compile after updating.

v1.2.1 August 11, 2026

New

FeatShips a ready-made Container Size attribute (Text Swatch), pre-seeded with two starter options, so a fresh install has a working configurable-size attribute out of the box
FeatMass delete added to the Brands, Colours, and Prices admin grids

Fixes

FixThe Price grid's Container Size dropdown and column previously referenced a nonexistent attribute code and always rendered empty or crashed in production mode
FixThe single-row "Delete" confirmation dialog on the Brands, Colours, and Prices grids showed a raw unresolved template string instead of the record's name

💡

Run bin/magento setup:di:compile after updating, in addition to setup:upgrade — this release adds new admin controller actions that production mode's compiled action list needs to pick up.

v1.2.0 August 11, 2026

New

FeatRedesigned colour-selection experience: a guided step-by-step wizard (Colour Palette → Brand → Colour → Container Size)
FeatColours can be grouped into palette families for quicker browsing

Improvements

ImprSelected brand now shown alongside colour and size in the cart and order summary
ImprImproved alignment of the quantity field and Add to Cart button

Compatibility

FixFixed a compatibility issue that could prevent the colour guide admin grids from loading correctly in certain production environments

Database

FeatNew colourfamily column on the colours table, added automatically on upgrade

v1.1.0 August 10, 2026

Security

SecFixed a price-manipulation issue where cart pricing for colour/size selections could be influenced by a client-submitted value instead of the admin-configured price table; pricing is now always re-derived server-side from Brand/Colour/Price data
SecScoped admin permissions for all Colorguide admin screens (brands, colours, prices) to a dedicated ACL resource, so access can be restricted per admin role like any other Magento admin section
SecRemoved an overly broad internal flag that was being set on every add-to-cart action storefront-wide instead of only Colorguide-priced items

Improvements

ImprConfirmed compatibility with PHP 8.1+ and Magento 2.4.x
ImprFixed an edge case where selecting a colour/size combination with no matching price could return an empty response instead of a clear price
ImprReplaced ad-hoc dependency lookups with standard Magento dependency injection throughout
ImprGeneral code cleanup: removed dead configuration and leftover development placeholders

💡

Run bin/magento setup:upgrade after installing or updating the extension.