Use Color

Create colors

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";

// Create colors from RGB (values from 0 to 1)
const red = colorUtils.fromRGB(1, 0, 0);

// Create colors from HEX
const green = colorUtils.fromHex("#00FF00");

// Create a rectangle and apply the red color
const rect = editor.createRectangle();
rect.width = 200;
rect.height = 100;
rect.translation = { x: 100, y: 100 };
rect.fill = editor.makeColorFill(red);
editor.context.insertionParent.children.append(rect);

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

Apply colors

You can directly set the color property of a Text node via applyCharacterStyles():

Example: Text color

// sandbox/code.js
import { editor, colorUtils } from "express-document-sdk";

// Create a text node
const textNode = editor.createText("Hello, World!");
const insertionParent = editor.context.insertionParent;
textNode.translation = { x: 100, y: 100 };
insertionParent.children.append(textNode);

// Apply character styles to the first five letters
textNode.fullContent.applyCharacterStyles(
  { color: colorUtils.fromHex("#E1A141") },
  { start: 0, length: 5 }
);

See the Use Text page for more examples.

Example: Fill and Stroke colors

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.rx = 100;
ellipse.ry = 50;
ellipse.translation = { x: 150, y: 150 };

// 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,
});
// ...

data-slots=header, text

data-variant=info

Use the Color Picker

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.

Benefits

• It simplifies the process of selecting a color, bypassing the Browser's color picker.
• It's in sync with any swatches or Brand colors defined in Adobe Express.
• It will evolve with Adobe Express, providing a consistent color picking experience across different parts of the application.

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:

1. Anchor Element

• Pass an HTML element reference as the first argument.
• The color picker will position itself relative to this element.
• Use the ColorPickerPlacement enum to control positioning.

2. Event Handling

• The anchor element receives two custom events:

  • "colorpicker-color-change": Fires when a new color is selected.
  • "colorpicker-close": Fires when the picker is closed.

Example: Show the Color Picker

data-slots=heading, code

data-repeat=2

import addOnUISdk, {
  ColorPickerEvent,
  ColorPickerPlacement,
} from "https://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(ColorPickerEvent.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(ColorPickerEvent.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.

Example: Hide the Color Picker

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);
});

Example: Use the color

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.

data-slots=heading, code

data-repeat=2

<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(ColorPickerEvent.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
}

FAQs

Q: How do I create colors from RGB values?

A: Use colorUtils.fromRGB(r, g, b, alpha) with values from 0 to 1.

Q: How do I create colors from HEX values?

A: Use colorUtils.fromHex("#RRGGBB") or colorUtils.fromHex("#RRGGBBAA") for colors with alpha.

Q: How do I convert a color to HEX string?

A: Use colorUtils.toHex(color) to get HEX string with alpha included.

Q: How do I apply color to text?

A: Use textNode.fullContent.applyCharacterStyles({ color }, range) with a Color object.

Q: How do I apply fill color to shapes?

A: Use shape.fill = editor.makeColorFill(color) to apply solid color fills.

Q: How do I apply stroke color to shapes?

A: Use shape.stroke = editor.makeStroke({ color, width }) to apply colored strokes.

Q: How do I show the native color picker?

A: Call addOnUISdk.app.showColorPicker(anchorElement, options) to display the picker.

Q: How do I handle color picker events?

A: Listen for "colorpicker-color-change" and "colorpicker-close" events on the anchor element.