@knime/ui-extension-renderer

Internal shared components and utilities to render UI-Extensions. Used in other consuming @knime packages.

Installation

To install the @knime/ui-extension-renderer package, you can use npm:

npm install @knime/ui-extension-renderer

Usage

To use it in your vue project, you can import it as follows:

import { UIExtension } from "@knime/ui-extension-renderer/vue";

or import types as follow:

import type { ExtensionConfig } from "@knime/ui-extension-renderer/vue";

Dark mode

Pass the embedder's dark mode to UIExtension and it reaches iframe-based extensions on its own:

<script setup lang="ts">
import { useKdsDarkMode } from "@knime/kds-components";
import { UIExtension } from "@knime/ui-extension-renderer/vue";

const { isDark } = useKdsDarkMode();
</script>

<template>
  <UIExtension
    :extension-config="extensionConfig"
    :resource-location="resourceLocation"
    :api-layer="apiLayer"
    :dark-mode="isDark"
  />
</template>

Pass the effective mode, not the preference

darkMode is a boolean: whether the embedder renders dark right now. If your app has a three-state preference (light / dark / system), resolve it first — useKdsDarkMode() exposes isDark for exactly this, alongside the preference-only isDarkPreferred.

Resolving in the embedder is deliberate. An extension may need a light/dark answer synchronously for something CSS cannot reach — a canvas, a charting library's options object — and it has no way to check whether its own prefers-color-scheme agrees with the embedder's. One resolution, in the embedder, means the two can never disagree.

How it is delivered

Two mechanisms, because neither alone is enough:

• On load, the mode goes on the iframe src as ?kdsDarkMode=true|false. The extension can therefore read it synchronously, before any round-trip, and paint the correct theme on its first render. Delivering the initial mode by message instead would paint light and then switch — a flash on every load.
• On change, a DarkModeEvent push event re-themes in place. The src keeps the mode the extension was loaded with, so toggling the theme never reloads the iframe and never discards its state.

Leaving darkMode unset propagates nothing at all, which is not the same as passing false. SHADOW_APP extensions never receive either: they render in the embedder's own document, which the embedder already themes.

An embedder that builds the iframe URL itself can use the same helpers directly:

import {
  DARK_MODE_QUERY_PARAM,
  appendDarkModeToUrl,
  getDarkModeFromQuery,
} from "@knime/ui-extension-renderer/api";

appendDarkModeToUrl() appends textually rather than through the URL API, so the KNIME desktop's custom-protocol URLs survive intact, and it inserts the parameter before any fragment so it stays part of the query string.

The extension side of this contract lives in @knime/ui-extension-service.

Join the Community!

• KNIME Forum