Letterbox background palette

Letterbox Palette helps editors choose matching side colors for portrait images used in wide hero layouts. Upload a vertical image, pick a dominant color (or edge gradient), and preview the letterbox background before saving.

Features

Letterbox Palette extracts a ranked color palette from a portrait image (GD, no external color library) and shows a live letterbox preview on the node form.

• Dominant swatches plus left / center / right edge colors for gradients
• Solid background or edge-to-edge gradient toggle
• AJAX-safe refresh when an image is uploaded or removed
• Per-content-type field mappings (image → color text field → optional boolean)
• Optional placement inside a Field Group
• Stores the choice as a plain #rrggbb value your theme can use

Use it when a vertical poster / hero image sits on a wide desktop canvas and needs matching side colors—festival pages, media heroes, editorial landing pages, and similar layouts.

Post-Installation

1. On each content type you want to use, create:
   • an Image field (source)
   • a Text (plain) field for the hex color (max length ≥ 7)
   • optionally a Boolean field for the gradient toggle
2. Go to Configuration → Content authoring → Letterbox Palette (/admin/config/content/letterbox-palette).
3. Add a mapping: content type, image field, color field, optional gradient field and Field Group machine name.
4. Optionally set the preview image style and CSS aspect ratio (default 16 / 7).
5. Edit a node, upload a portrait image, pick a swatch (and gradient if enabled), then save.

Landscape images show a hint only—the palette is proposed for portraits. Your front-end theme reads the stored hex / boolean fields and applies background-color or a CSS gradient around an object-fit: contain hero.

Additional Requirements

• Drupal core ^10 || ^11 (modules: Node, File, Image, Field)
• PHP >= 8.1 with the GD extension

No Composer color libraries and no third-party APIs.

Recommended modules/libraries

• Field Group — place the palette UI inside an existing form group (supported via the optional group machine name in settings)

Similar projects

Color / image tools such as Color Field, ImageColor, or theme-side dominant-color extractors focus on storing a color or analyzing an image in isolation.

Letterbox Palette is editor-workflow oriented: it ties extraction to a portrait letterbox preview, optional edge gradients, and configurable content-type mappings so authors pick the background in context before save.

Supporting this Module

Bug reports and feature requests: the issue queue. Contributions and merge requests are welcome.

Community Documentation

• README in the project repository
• Service API: \Drupal::service('letterbox_palette.extractor')->extractPortraitPalette($file) returns ranked colors and edge hex values for custom integrations

Notes

• Only portrait images (height ≥ width) produce a palette.
• Themes remain responsible for front-end letterboxing.
• Origin: generalized from a production France Télévisions (& Vous) festival editorial workflow.