Colors in Adobe Express are created as instances of the Color class: objects with red, green, blue, and alpha (optional) values in the range from 0 to 1. The alpha value represents the opacity of the color, with 0 being fully transparent and 1 fully opaque.
The entrypoint for creating colors is the colorUtils class, imported from the "express-document-sdk", so we’re talking about Document APIs here. Especially the static fromRGB() and fromHex() methods.
// sandbox/code.js
import { editor, colorUtils } from "express-document-sdk";
// Alpha is optional, defaults to 1
const red = colorUtils.fromRGB(1, 0, 0);
const green = colorUtils.fromHex("#00FF00");
// With alpha
const feldgrau = colorUtils.fromRGB(0.28, 0.32, 0.39, 0.5); // 50% opacity
const heliotrope = colorUtils.fromHex("#C768F780"); // 50% opacity
In case you need it, you can also convert a color to a HEX string using the toHex() method. Please note that the alpha value is always included in the output string.
const red = colorUtils.fromRGB(1, 0, 0);
const redHex = colorUtils.toHex(red); // #FF0000FF
You can directly set the color property of a Text node via applyCharacterStyles():
// sandbox/code.js
import { editor, colorUtils } from "express-document-sdk";
// Assuming the user has selected a text frame
const textNode = editor.context.selection[0];
// Apply character styles to the first three letters
textNode.fullContent.applyCharacterStyles(
{ color: colorUtils.fromHex("#E1A141") }, // 👈
{ start: 0, length: 3 }
);
See the Use Text page for more examples.
Colors are not directly applied, instead, to shapes; more generally, they are used to create Fill and Stroke objects with the editor.makeColorFill() and editor.makeStroke() methods, respectively, that you can then apply to Fillable and Strokable nodes.
If you’re confused, worry not! This is the wondrous word of object oriented programming. The following example should clarify things:
// sandbox/code.js
import { editor, colorUtils } from "express-document-sdk";
// Create the shape
const ellipse = editor.createEllipse();
ellipse.width = 100;
ellipse.height = 50;
ellipse.translation = { x: 50, y: 50 };
// Generate the needed colors
const innerColor = colorUtils.fromHex("#A38AF0");
const outerColor = colorUtils.fromHex("#2ACfA9");
// Make the colorFill and the Stroke
const innerColorFill = editor.makeColorFill(innerColor);
const outerColorStroke = editor.makeStroke({
color: outerColor,
width: 20,
});
// 👇 Apply the fill and stroke
ellipse.fill = innerColorFill;
ellipse.stroke = outerColorStroke;
// Add the shape to the document
editor.context.insertionParent.children.append(ellipse);
While the fill property is more straightforward to create, the color is just one of the possible properties of a stroke, as you can read in the SolidColorStroke interface reference.
Simplifying the example above:
// ...
ellipse.fill = editor.makeColorFill(colorUtils.fromHex("#A38AF0"));
ellipse.stroke = editor.makeStroke({
color: colorUtils.fromHex("#2ACfA9"),
width: 20,
});
// ...
Naming conventions
Please note that Adobe Express uses the terms make and create to distinguish between plain objects and live document objects. You makeColorFill(), but createEllipse().
Adobe Express includes a native Color Picker, with special features such as Recommended Swatches, Eyedropper, Themes, Library and Brand colors. The Color Picker is available also to add-ons, you can invoke it using the addOnUISdk.app.showColorPicker() method.
IMPORTANT: This is currently experimental only and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the experimentalApis flag to true in the requirements section of the manifest.json.
The showColorPicker() method accepts a reference to an HTML element as its first argument, which will become the color picker’s anchor element. The picker will be positioned relative to this element, based on the placement options available in the ColorPickerPlacement enum; additionally, the anchor will receive a custom "colorpicker-color-change" event when the color changes and a "colorpicker-close" event when it is closed.
The showColorPicker() method requires an HTML element as its anchor point. Here’s how it works:
ColorPickerPlacement enum to control positioning."colorpicker-color-change": Fires when a new color is selected."colorpicker-close": Fires when the picker is closed.import addOnUISdk, {
ColorPickerEvents,
ColorPickerPlacement,
} from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
addOnUISdk.ready.then(async () => {
// Get the button element
const colorPickerButton = document.getElementById("colorPicker");
// Add a click event listener to the button to show the color picker
colorPickerButton.addEventListener("click", () => {
addOnUISdk.app.showColorPicker(colorPickerButton, {
// The title of the color picker
title: "Awesome Color Picker",
// The placement of the color picker
placement: ColorPickerPlacement.left,
// Whether the eyedropper hides the color picker
eyedropperHidesPicker: true,
// The initial color of the color picker
initialColor: 0x0000ff,
// Whether the alpha channel is disabled
disableAlphaChannel: false,
});
});
// Add a listener for the colorpicker-color-change event
colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
// Get the color from the event
console.log(event.detail.color);
// e.g., "#F0EDD8FF" in HEX (RRGGBBAA) format
});
// Add a listener for the colorpicker-close event
colorPickerButton.addEventListener(ColorPickerEvents.close, (event) => {
console.log(event.type); // "colorpicker-close"
});
});
<button id="colorPicker">Show the Color Picker</button>
Please note that the color returned by the colorpicker-color-change event is always a string in HEX format—with or without an alpha value, e.g., #F0EDD8FF or #F0EDD8 depending on the disableAlphaChannel option.
You can decide to hide picker UI e.g., after a certain amount of time.
colorPickerButton.addEventListener("click", () => {
addOnUISdk.app.showColorPicker(colorPickerButton, {
/* ... */
});
setTimeout(() => {
console.log("Hiding the Color Picker after 10 seconds");
addOnUISdk.app.hideColorPicker();
}, 10000);
});
You can use any HTML element as the color picker’s anchor element; in the example below, we’re using a <div> element to display a color swatch.
<style>
#color-display {
width: 30px;
height: 30px;
border: 1px solid black;
border-radius: 4px;
background-color: white;
}
</style>
<body>
<div id="color-display"></div>
</body>
addOnUISdk.ready.then(async () => {
const colorDisplay = document.getElementById("color-display");
colorDisplay.addEventListener("click", () => {
addOnUISdk.app.showColorPicker(colorDisplay, {
title: "Color Picker 1",
placement: ColorPickerPlacement.left,
eyedropperHidesPicker: true,
});
});
colorDisplay.addEventListener(ColorPickerEvents.colorChange, (event) => {
// Update the color swatch display in the UI
colorDisplay.style.backgroundColor = event.detail.color;
});
});
To use the picked color in the Document Sandbox, you can use the colorUtils.fromHex() method, which converts the HEX color string to a Color object.
// sandbox/code.js
const color = colorUtils.fromHex(event.detail.color); // 👈 A Color object
// Use the color in the Document Sandbox, for example:
let selection = editor.context.selection;
if (selection.length === 1 && selection[0].type === "Text") {
const textContentModel = selection[0].fullContent;
textContentModel.applyCharacterStyles({ color }); // 👈 Using the color
}