Theming - Next.js | IMG.LY Docs

Theming involves adjusting the colors, fonts, and sizes of the Editor UI. We have provisioned three levels of support for themes:

Our built-in themes can be used out-of-the-box.
Our theme generator can be used for quickly generating new themes based on three main colors
A custom theme can be added by leveraging our theming API for the most detailed customization of our UI.

Using the built-in Themes and Scale#

We provide three built-in theme options and three scale settings that can be configured at runtime:

Theme Management#

Use the following methods to manage themes at runtime:

cesdk.ui.setTheme(theme) - Sets the theme to ‘light’, ‘dark’, or ‘system’ (which follows the OS preference)
cesdk.ui.getTheme() - Returns the current theme (‘light’ or ‘dark’)

By default, the ‘light’ theme is active. The ‘system’ option automatically adapts to the user’s OS theme preference.

Scale Management#

Use the following methods to manage UI scale at runtime:

cesdk.ui.setScale(scale) - Sets the UI scale to ‘normal’, ‘large’, ‘modern’, or a function that returns one of these values
cesdk.ui.getScale() - Returns the current scale setting

The scale modes offer different visual experiences:

normal: Standard UI scaling for desktop and larger screens
large: Increased UI element sizes, margins, and fonts for improved readability and accessibility, particularly beneficial for users with visual or motor impairments and those on small screens
modern: Modern theme with refined color palette, unified elevation surfaces, and improved visual hierarchy

For more flexibility, a callback can be passed that returns ‘normal’, ‘large’, or ‘modern’ based on viewport properties:

containerWidth - The width of the HTML element containing the CE.SDK editor
isTouch - Boolean indicating if the user agent supports touch input

import CreativeEditorSDK from 'https://cdn.img.ly/packages/imgly/cesdk-js/1.63.0/index.js';

const config = {
  // license: 'YOUR_CESDK_LICENSE_KEY',
  userId: 'guides-user',
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-js/1.63.0/assets'
};

CreativeEditorSDK.create('#cesdk_container', config).then(async (cesdk) => {
  // Set theme at runtime (can be 'light', 'dark', or 'system')
  cesdk.ui.setTheme('light');

  // Set scale dynamically based on viewport
  cesdk.ui.setScale(({ containerWidth, isTouch }) => {
    if (containerWidth < 600 || isTouch) {
      return 'large';
    } else {
      return 'normal';
    }
  });
  // Or simply set a fixed scale:
  // cesdk.ui.setScale('normal');
  // cesdk.ui.setScale('large');
  // cesdk.ui.setScale('modern');

  // Get the current theme
  const currentTheme = cesdk.ui.getTheme(); // 'light' or 'dark'

  // Get the current scale setting
  const currentScale = cesdk.ui.getScale(); // 'normal', 'large', 'modern', or function

  // Populate the asset library with default / demo asset sources.
  cesdk.addDefaultAssetSources();
  cesdk.addDemoAssetSources({
    sceneMode: 'Design',
    withUploadAssetSources: true
  });
  await cesdk.createDesignScene();
});

Using the Theme Generator#

In order to get started quickly with building a custom theme, use our built-in theme generator found in the ‘Settings’ panel. Using only three base colors, this will generate a theme file that you can directly use. See Theming API below on how to provide your theme.

elements: {
  panels: {
    settings: true;
  }
}

Using a Custom Theme#

To provide a theme to the editor, link your themes index.css files or populate a <style> tag on the same page that includes the editor.

.ubq-public[data-ubq-theme='dark'][data-ubq-scale='normal'] {
  --ubq-canvas: hsl(230.27, 52.11%, 13.92%);
  --ubq-elevation-1: hsl(230.4, 52.08%, 18.82%);
  --ubq-elevation-2: hsl(229.69, 52.46%, 23.92%);
  --ubq-foreground-default: hsla(0, 0%, 100%, 0.9);
  --ubq-foreground-light: hsla(0, 0%, 100%, 0.7);
  --ubq-foreground-info: hsla(0, 0%, 100%, 0.5);
  --ubq-interactive-default: hsl(229.87, 52.38%, 28.82%);
  --ubq-interactive-hover: hsl(229.69, 52.46%, 23.92%);
  --ubq-interactive-pressed: hsl(230.45, 52.38%, 16.47%);
  --ubq-input-default: hsl(234, 50%, 3.92%);
  --ubq-input-hover: hsl(228, 55.56%, 1.76%);
  --ubq-border-default: hsla(230, 52.17%, 63.92%, 0.1);
  --ubq-stroke-contrast-1: hsla(230, 52.17%, 63.92%, 0.08);
  --ubq-stroke-contrast-2: hsla(230, 52.17%, 63.92%, 0.25);
  --ubq-focus-outline: hsl(230.27, 52.11%, 13.92%);
  --ubq-overlay-default: hsla(230.27, 52.11%, 13.92%, 0.8);
  --ubq-foreground-active: hsla(210, 30%, 10%, 0.9);
  --ubq-interactive-active-default: linear-gradient(
      to bottom,
      hsla(0, 0%, 100%, 1),
      hsla(0, 0%, 100%, 0)
    ), hsla(0, 0%, 100%, 0.88);
  --ubq-interactive-active-hover: linear-gradient(
      to bottom,
      hsla(0, 0%, 100%, 1),
      hsla(0, 0%, 100%, 0)
    ), hsla(210, 100%, 95%, 0.98);
  --ubq-interactive-active-pressed: linear-gradient(
      to bottom,
      hsla(0, 0%, 100%, 1),
      hsla(0, 0%, 100%, 0)
    ), hsla(0, 0%, 100%, 0.5);
  --ubq-notice-info: hsla(0, 0%, 100%, 1);
  --ubq-foreground-accent: hsl(0, 0%, 0%);
  --ubq-interactive-accent-default: hsl(0, 0%, 100%);
  --ubq-interactive-accent-hover: hsl(0, 0%, 100%);
  --ubq-interactive-accent-pressed: hsl(0, 0%, 95%);
  --ubq-focus-default: hsl(288.99, 0%, 92.5%);
  --ubq-notice-warning: hsl(37.45, 0%, 93.5%);
  --ubq-notice-error: hsl(311.23, 0%, 88.9%);
  --ubq-notice-success: hsl(166.23, 0%, 92.19%);

  --ubq-typography-headline-l-size: 16px;
  --ubq-typography-headline-l-line_height: 20px;
  --ubq-typography-headline-l-letter_spacing: 0.01em;
  --ubq-typography-headline-l-font_family: var(
    --ubq-typography-font_family,
    'Inter',
    sans-serif
  );
  --ubq-typography-headline-l-weight: 600;

  --ubq-typography-headline-m-size: 12px;
  --ubq-typography-headline-m-line_height: 16px;
  --ubq-typography-headline-m-letter_spacing: 0.03em;
  --ubq-typography-headline-m-font_family: var(
    --ubq-typography-font_family,
    'Inter',
    sans-serif
  );
  --ubq-typography-headline-m-weight: 600;

  --ubq-typography-label-m-size: 12px;
  --ubq-typography-label-m-line_height: 16px;
  --ubq-typography-label-m-letter_spacing: 0.02em;
  --ubq-typography-label-m-font_family: var(
    --ubq-typography-font_family,
    'Inter',
    sans-serif
  );
  --ubq-typography-label-m-weight: normal;

  --ubq-typography-label-s-size: 10px;
  --ubq-typography-label-s-line_height: 14px;
  --ubq-typography-label-s-letter_spacing: 0.02em;
  --ubq-typography-label-s-font_family: var(
    --ubq-typography-font_family,
    'Inter',
    sans-serif
  );
  --ubq-typography-label-s-weight: normal;

  --ubq-typography-body-m-size: 12px;
  --ubq-typography-body-m-line_height: 18px;
  --ubq-typography-body-m-letter_spacing: 0.02em;
  --ubq-typography-body-m-font_family: var(
    --ubq-typography-font_family,
    'Inter',
    sans-serif
  );
  --ubq-typography-body-m-weight: normal;

  --ubq-typography-input-m-size: 12px;
  --ubq-typography-input-m-line_height: 16px;
  --ubq-typography-input-m-letter_spacing: 0.02em;
  --ubq-typography-input-m-font_family: var(
    --ubq-typography-font_family,
    'Inter',
    sans-serif
  );
  --ubq-typography-input-m-weight: unset;

  --ubq-typography-button-m-size: 12px;
  --ubq-typography-button-m-line_height: 16px;
  --ubq-typography-button-m-letter_spacing: 0.02em;
  --ubq-typography-button-m-font_family: var(
    --ubq-typography-font_family,
    'Inter',
    sans-serif
  );
  --ubq-typography-button-m-weight: unset;
}

Theming API#

Our theming API consists of several custom CSS properties, allowing you to adapt the look and feel of the editor to your needs.

To limit the scope of a theme to the CE.SDK Editor UI wrap any CSS properties in the ubq-public class.

The CE.SDK Editor supports switching between dark and light mode UI, which is a popular default in current operating systems. To adjust your theme based on that switch, use the data attribute data-ubq-theme.

The CE.SDK Editor also supports switching between ‘normal’, ‘large’, and ‘modern’ scale modes. The data attribute data-ubq-scale contains information on which scaling is currently requested: