iCUE Widgets

https://docs.elgato.com/icue/
Admin
iCUE Widgets allows developers to build, validate, and package interactive HTML-based widgets for...
Tokens:42,307
Snippets:399
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example Manifest

Source: https://docs.elgato.com/icue/widgets/specification

A complete manifest.json example showing required and optional properties, including supported devices and required plugins.

```json
{
	"author": "Corsair Team",
	"id": "com.corsair.weatherwidget",
	"name": "Weather Widget",
	"description": "Display current weather and forecast",
	"version": "1.0.0",
	"preview_icon": "resources/icon.png",
	"min_app_version": "5.46",
	"min_framework_version": "1.0.0",
	"os": [
		{
			"platform": "windows"
		}
	],
	"supported_devices": [
		{
			"type": "dashboard_lcd",
			"features": ["sensor-screen"]
		},
		{
			"type": "pump_lcd"
		},
		{
			"type": "keyboard_lcd"
		}
	],
	"interactive": true,
	"required_plugins": [
		"widgetbuilder.sensorsdataprovider:Sensors:1.0",
		"widgetbuilder.mediadataprovider:Media:1.0"
	],
	"modules": [
		"modules/CitySearch.mjs"
	]
}
```

--------------------------------

### Example: manifest.json and index.html for DeviceAction

Source: https://docs.elgato.com/icue/widgets/references/plugins/device-action-provider

Complete example showing the manifest entry and the JavaScript code to initialize the plugin and connect to the dialTriggered signal.

```json
"required_plugins": [
  "widgetbuilder.deviceactionprovider:DeviceAction:1.0"
]
```

```javascript
function onDialTriggered(actionType, dialIndex) {
    console.log("Action:", actionType, "Dial:", dialIndex);
}

pluginDeviceactionproviderEvents = {
    "onInitialized": function () {
        if (!window.plugins || !window.plugins.Deviceactionprovider) {
            return;
        }

        window.plugins.Deviceactionprovider.initDevice(device.deviceId);

        window.plugins.Deviceactionprovider.dialTriggered.connect(onDialTriggered);
    }
};

if (typeof pluginDeviceactionprovider_initialized !== "undefined" && pluginDeviceactionprovider_initialized) {
    pluginDeviceactionproviderEvents.onInitialized();
}
```

--------------------------------

### Complete widget HTML example

Source: https://docs.elgato.com/icue/widgets/references/controls/sensors-combobox

Full HTML document for the complete widget example. It includes the meta property for sensors-combobox, groups definition, script includes for IcueWidgetApiWrapper and SimpleSensorApiWrapper, and JavaScript to display sensor values. Requires icon.svg and the common folder from the iCUE installation.

```html
<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>'Sensors Combobox Demo'</title>
        <link rel="icon" type="image/svg+xml" href="resources/icon.svg" />

        <meta
            name="x-icue-property"
            content="sensorId"
            data-label="'Sensor'"
            data-type="sensors-combobox"
            data-default="plugins.Sensorsdataprovider.getDefaultSensorIdBlock('temperature')"
        />

        <script type="application/json" id="x-icue-groups">
            [{ "title": "'Settings'", "properties": ["sensorId"] }]
        </script>

        <script src="common/plugins/IcueWidgetApiWrapper.js"></script>
        <script src="common/plugins/SimpleSensorApiWrapper.js"></script>
    </head>
    <body
        style="margin:0;height:100vh;display:flex;align-items:center;justify-content:center;background:#1a1a2e;color:#fff;font-family:sans-serif;"
    >
        <div>
            <span id="value" style="font-size:48px;">--</span>
            <span id="units" style="font-size:24px;"></span>
        </div>
        <script>
            let api = null;
            icueEvents = { onDataUpdated: update, onICUEInitialized: update };
            pluginSensorsdataproviderEvents = { onInitialized: onPluginReady };

            function onPluginReady() {
                api = new SimpleSensorApiWrapper(window.plugins.Sensorsdataprovider);
                window.plugins.Sensorsdataprovider.sensorValueChanged.connect((id, val) => {
                    if (id === sensorId) document.getElementById("value").textContent = parseFloat(val).toFixed(1);
                });
                update();
            }

            async function update() {
                if (!api || !sensorId) return;
                const [val, units] = await Promise.all([api.getSensorValue(sensorId), api.getSensorUnits(sensorId)]);
                document.getElementById("value").textContent = parseFloat(val).toFixed(1);
                document.getElementById("units").textContent = units;
            }

            if (iCUE_initialized) update();
            if (typeof pluginSensorsdataprovider_initialized !== "undefined" && pluginSensorsdataprovider_initialized)
                onPluginReady();
        </script>
    </body>
</html>
```

--------------------------------

### Complete widget example - manifest

Source: https://docs.elgato.com/icue/widgets/references/controls/media-selector

Manifest file for a complete media-selector widget example, specifying author, ID, name, supported OS, and devices.

```json
{
    "author": "Corsair Team",
    "id": "com.corsair.mediaselectordemo",
    "name": "Media Selector Demo",
    "description": "Media Selector Demo",
    "version": "1.0.0",
    "preview_icon": "icon.png",
    "min_framework_version": "1.0.0",
    "os": [
        {
            "platform": "windows"
        },
        {
            "platform": "mac"
        }
    ],
    "supported_devices": [
        {
            "type": "dashboard_lcd",
            "features": ["sensor-screen"]
        },
        {
            "type": "pump_lcd"
        },
        {
            "type": "keyboard_lcd"
        }
    ]
}
```

--------------------------------

### Complete widget example - HTML

Source: https://docs.elgato.com/icue/widgets/references/controls/media-selector

HTML file for the complete media-selector widget example, including the meta tag, MediaViewer integration, and update logic.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>'Media Selector Demo'</title>
    <link rel="icon" type="image/svg+xml" href="resources/icon.svg">

    <meta name="x-icue-property" content="backgroundImage"
          data-label="tr('Background Image')" data-type="media-selector"
          data-filters="['*.png', '*.jpg', '*.gif']">

    <script type="application/json" id="x-icue-groups">
    [{"title": "tr('Settings')", "properties": ["backgroundImage"]}]
    </script>

    <!-- Bundle these files from docs/common into your widget folder -->
    <link rel="stylesheet" href="common/tools/media_viewer/MediaViewer.css">
    <script src="common/tools/media_viewer/MediaViewer.js"></script>
</head>
<body style="margin:0;height:100vh;background:#1a1a2e;color:#fff;font-family:sans-serif;">
    <div id="media" style="position:relative;width:100%;height:100%;"></div>
    <div id="info" style="position:relative;z-index:1;padding:20px;">No media</div>
    <script>
        const viewer = new MediaViewer({ container: document.getElementById("media") });
        icueEvents = { "onDataUpdated": update, "onICUEInitialized": update };

        function update() {
            if (typeof backgroundImage === "undefined") {
                viewer.clear();
                document.getElementById("info").textContent = "No media";
            } else {
                viewer.loadMedia({
                    path: backgroundImage.pathToAsset,
                    baseWidth: backgroundImage.baseWidth,
                    baseHeight: backgroundImage.baseHeight,
                    scale: backgroundImage.scale,
                    positionX: backgroundImage.positionX,
                    positionY: backgroundImage.positionY,
                    angle: backgroundImage.angle
                });
            }
        }
        if (iCUE_initialized) update();
    </script>
</body>
</html>
```

--------------------------------

### Example: manifest.json and index.html for Media Data Provider

Source: https://docs.elgato.com/icue/widgets/references/plugins/media-data-provider

Complete example showing the manifest entry and usage in index.html. The JavaScript initializes the wrapper, fetches song name and artist asynchronously, and demonstrates synchronous playback controls.

```json
"required_plugins": [
  "widgetbuilder.mediadataprovider:Media:1.0"
]
```

```javascript
// After including IcueWidgetApiWrapper and SimpleMediaApiWrapper in <head>:
const mediaApi = new SimpleMediaApiWrapper(window.plugins.Mediadataprovider);

async function displayCurrentTrack() {
    const [songName, artist] = await Promise.all([
        mediaApi.getSongName(),
        mediaApi.getArtist(),
    ]);
    console.log(`Now playing: ${songName} by ${artist}`);
}

// Playback controls (synchronous — call directly on the plugin)
window.plugins.Mediadataprovider.triggerPlayPause();
window.plugins.Mediadataprovider.triggerNextTrack();
window.plugins.Mediadataprovider.triggerPreviousTrack();
```

--------------------------------

### Complete widget example - Manifest

Source: https://docs.elgato.com/icue/widgets/references/controls/switch

Manifest file for a complete switch widget example. It defines the widget metadata, supported platforms, and devices.

```json
{
  "author": "Corsair Team",
  "id": "com.corsair.switchdemo",
  "name": "Switch Demo",
  "description": "Switch Demo",
  "version": "1.0.0",
  "preview_icon": "icon.png",
  "min_framework_version": "1.0.0",
  "os": [
    {
      "platform": "windows"
    },
    {
      "platform": "mac"
    }
  ],
  "supported_devices": [
    {
      "type": "dashboard_lcd",
      "features": ["sensor-screen"]
    },
    {
      "type": "pump_lcd"
    },
    {
      "type": "keyboard_lcd"
    }
  ]
}
```

--------------------------------

### Example: display all sensors with SimpleSensorApiWrapper

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

After including IcueWidgetApiWrapper and SimpleSensorApiWrapper in the <head>, this example creates a wrapper instance and asynchronously logs the name, value, and units for every sensor. It uses Promise.all to fetch sensor data concurrently.

```javascript
// After including IcueWidgetApiWrapper and SimpleSensorApiWrapper in <head>:
const sensorApi = new SimpleSensorApiWrapper(window.plugins.Sensorsdataprovider);

async function displayAllSensors() {
    const sensorIds = await sensorApi.getAllSensorIds();
    for (const sensorId of sensorIds) {
        const [name, value, units] = await Promise.all([
            sensorApi.getSensorName(sensorId),
            sensorApi.getSensorValue(sensorId),
            sensorApi.getSensorUnits(sensorId),
        ]);
        console.log(`${name}: ${value} ${units}`);
    }
}
displayAllSensors();
```

--------------------------------

### Device Support Example

Source: https://docs.elgato.com/icue/widgets/specification

Shows how to specify supported devices with optional feature requirements in the manifest.

```json
"supported_devices": [
    {
        "type": "dashboard_lcd",
        "features": ["sensor-screen"]
    },
    {
        "type": "pump_lcd"
    }
]
```

--------------------------------

### Complete widget example - HTML

Source: https://docs.elgato.com/icue/widgets/references/controls/switch

HTML file for a complete switch widget example. It includes the switch meta tag, a group definition, and JavaScript to update the display based on the switch value.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>'Switch Demo'</title>
    <link rel="icon" type="image/svg+xml" href="resources/icon.svg">

    <meta name="x-icue-property" content="showLabel"
          data-label="'Show Label'" data-type="switch" data-default="true">

    <script type="application/json" id="x-icue-groups">
    [{"title": "'Settings'", "properties": ["showLabel"]}]
    </script>
</head>
<body style="margin:0;height:100vh;display:flex;align-items:center;justify-content:center;background:#1a1a2e;color:#fff;font-family:sans-serif;">
    <div id="demo" style="font-size:48px;">ON</div>
    <script>
        icueEvents = { "onDataUpdated": update, "onICUEInitialized": update };
        function update() { document.getElementById("demo").textContent = showLabel ? "ON" : "OFF"; }
        if (iCUE_initialized) update();
    </script>
</body>
</html>
```

--------------------------------

### Complete Widget Example - Manifest

Source: https://docs.elgato.com/icue/widgets/references/controls/combobox

Manifest file for a complete combobox widget example. It defines the widget metadata, supported OS, and supported devices.

```json
{
  "author": "Corsair Team",
  "id": "com.corsair.comboboxdemo",
  "name": "Combobox Demo",
  "description": "Combobox Demo",
  "version": "1.0.0",
  "preview_icon": "icon.png",
  "min_framework_version": "1.0.0",
  "os": [
    {
      "platform": "windows"
    },
    {
      "platform": "mac"
    }
  ],
  "supported_devices": [
    {
      "type": "dashboard_lcd",
      "features": ["sensor-screen"]
    },
    {
      "type": "pump_lcd"
    },
    {
      "type": "keyboard_lcd"
    }
  ]
}
```

--------------------------------

### Install iCUE Widget CLI with npm

Source: https://docs.elgato.com/icue/widgets

Install the iCUE Widget CLI globally as an npm package. After installation, the `icuewidget` command becomes available in the terminal.

```bash
npm install -g icuewidget-cli
```

--------------------------------

### SimpleFpsApiWrapper usage example with manifest.json and index.html

Source: https://docs.elgato.com/icue/widgets/references/plugins/fps-data-provider

Complete example showing the manifest entry and the HTML/JavaScript code to fetch FPS data and process name using the wrapper. The manifest.json declares the required plugin, and index.html uses the wrapper to display FPS data.

```json
"required_plugins": [
  "widgetbuilder.fpsdataprovider:Fps:1.0"
]
```

```javascript
// After including IcueWidgetApiWrapper and SimpleFpsApiWrapper in <head>:
const fpsApi = new SimpleFpsApiWrapper(window.plugins.Fpsdataprovider);

async function displayFpsData() {
	const available = await fpsApi.getFpsAvailable();
	if (available) {
		const [fps, process] = await Promise.all([
			fpsApi.getCurrentFps(),
			fpsApi.getCurrentProcess()
		]);
		console.log(`${process}: ${fps} FPS`);
	}
}
displayFpsData();
```

--------------------------------

### Manifest required_plugins declaration (Example section)

Source: https://docs.elgato.com/icue/widgets/references/controls/sensors-combobox

Shows the required_plugins entry in the manifest as part of the example. This is the same plugin declaration as in the Requirements section.

```json
 "required_plugins": [
     "widgetbuilder.sensorsdataprovider:Sensors:1.0"
 ]
```

--------------------------------

### JavaScript usage example for sensorId

Source: https://docs.elgato.com/icue/widgets/references/controls/sensors-combobox

Shows how to access the selected sensor ID in JavaScript. The example logs 'cpu_temp_0' as a sample output.

```javascript
console.log(sensorId); // "cpu_temp_0"
```

--------------------------------

### Complete example: index.html

Source: https://docs.elgato.com/icue/widgets/references/translations

A complete HTML file using tr() in meta properties and groups, with a simple body.

```html
<!doctype html>
<html lang="en">
    <head>
        <title>tr('Clock')</title>

        <meta
            name="x-icue-property"
            content="timeZone"
            data-label="tr('Time Zone')"
            data-type="combobox"
            data-values="[{'key':'utc','value':tr('UTC')},{'key':'est','value':tr('EST')},{'key':'cst','value':tr('CST')}]"
        />

        <meta
            name="x-icue-property"
            content="textColor"
            data-label="tr('Text Color')"
            data-type="color"
            data-default="'#ffffff'"
        />

        <script type="application/json" id="x-icue-groups">
            [
                {
                    "title": "tr('Appearance')",
                    "properties": ["timeZone", "textColor"]
                }
            ]
        </script>
    </head>
    <body>
        <div id="time"></div>
    </body>
</html>
```

--------------------------------

### Complete Widget Example - HTML

Source: https://docs.elgato.com/icue/widgets/references/controls/combobox

HTML file for the complete combobox widget example. It includes the combobox meta tag, a group definition, and JavaScript to update the display based on the selected value.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>'Combobox Demo'</title>
    <link rel="icon" type="image/svg+xml" href="resources/icon.svg">

    <meta name="x-icue-property" content="fruit"
          data-label="'Fruit'" data-type="combobox"
          data-default="'apple'" data-values="['apple', 'banana', 'orange']">

    <script type="application/json" id="x-icue-groups">
    [{"title": "'Settings'", "properties": ["fruit"]}]
    </script>
</head>
<body style="margin:0;height:100vh;display:flex;align-items:center;justify-content:center;background:#1a1a2e;color:#fff;font-family:sans-serif;">
    <div id="demo" style="font-size:48px;">apple</div>
    <script>
        icueEvents = { "onDataUpdated": update, "onICUEInitialized": update };
        function update() { document.getElementById("demo").textContent = fruit; }
        if (iCUE_initialized) update();
    </script>
</body>
</html>
```

--------------------------------

### Complete Widget Example - Manifest

Source: https://docs.elgato.com/icue/widgets/references/controls/textfield

Manifest JSON for a complete textfield widget example. It defines the widget metadata, supported OS (Windows and Mac), and supported devices (dashboard_lcd, pump_lcd, keyboard_lcd).

```json
{
  "author": "Corsair Team",
  "id": "com.corsair.textfielddemo",
  "name": "Textfield Demo",
  "description": "Textfield Demo",
  "version": "1.0.0",
  "preview_icon": "icon.png",
  "min_framework_version": "1.0.0",
  "os": [
    {
      "platform": "windows"
    },
    {
      "platform": "mac"
    }
  ],
  "supported_devices": [
    {
      "type": "dashboard_lcd",
      "features": ["sensor-screen"]
    },
    {
      "type": "pump_lcd"
    },
    {
      "type": "keyboard_lcd"
    }
  ]
}
```

--------------------------------

### Complete Widget Example - HTML

Source: https://docs.elgato.com/icue/widgets/references/controls/textfield

HTML file for the complete textfield widget example. It includes the meta tag for the textfield property, a group definition, and JavaScript to update the display with the entered text. Requires an icon.svg file to work.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>'Textfield Demo'</title>
    <link rel="icon" type="image/svg+xml" href="resources/icon.svg">

    <meta name="x-icue-property" content="title"
          data-label="'Title'" data-type="textfield" data-default="'Hello World'">

    <script type="application/json" id="x-icue-groups">
    [{"title": "'Settings'", "properties": ["title"]}]
    </script>
</head>
<body style="margin:0;height:100vh;display:flex;align-items:center;justify-content:center;background:#1a1a2e;color:#fff;font-family:sans-serif;">
    <div id="demo" style="font-size:48px;">Hello World</div>
    <script>
        icueEvents = { "onDataUpdated": update, "onICUEInitialized": update };
        function update() { document.getElementById("demo").textContent = title; }
        if (iCUE_initialized) update();
    </script>
</body>
</html>
```

--------------------------------

### Complete Widget Example: Manifest and HTML

Source: https://docs.elgato.com/icue/widgets/references/controls/tab-buttons

A complete widget example for the tab-buttons control. The manifest defines the widget metadata and supported devices. The HTML includes the meta tag for the property, a group definition, and JavaScript to update the text alignment based on the selected value. Requires an icon.svg file.

```json
{
  "author": "Corsair Team",
  "id": "com.corsair.tabbuttonsdemo",
  "name": "Tab Buttons Demo",
  "description": "Tab Buttons Demo",
  "version": "1.0.0",
  "preview_icon": "icon.png",
  "min_framework_version": "1.0.0",
  "os": [
    {
      "platform": "windows"
    },
    {
      "platform": "mac"
    }
  ],
  "supported_devices": [
    {
      "type": "dashboard_lcd",
      "features": ["sensor-screen"]
    },
    {
      "type": "pump_lcd"
    },
    {
      "type": "keyboard_lcd"
    }
  ]
}
```

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>'Tab Buttons Demo'</title>
    <link rel="icon" type="image/svg+xml" href="resources/icon.svg">

    <meta name="x-icue-property" content="alignment"
          data-label="'Alignment'" data-type="tab-buttons"
          data-default="'center'"
          data-values="[{'key':'left','value':'Left'},{'key':'center','value':'Center'},{'key':'right','value':'Right'}]">

    <script type="application/json" id="x-icue-groups">
    [{"title": "'Settings'", "properties": ["alignment"]}]
    </script>
</head>
<body style="margin:0;height:100vh;display:flex;align-items:center;background:#1a1a2e;color:#fff;font-family:sans-serif;">
    <div id="demo" style="width:100%;font-size:48px;">Hello</div>
    <script>
        icueEvents = { "onDataUpdated": update, "onICUEInitialized": update };
        function update() { document.getElementById("demo").style.textAlign = alignment; }
        if (iCUE_initialized) update();
    </script>
</body>
</html>
```

--------------------------------

### QML example: Initialize and connect StreamDeck

Source: https://docs.elgato.com/icue/widgets/references/plugins/stream-deck

Shows how to import the widgetbuilder.streamdeck module, create a StreamDeck object, handle virtualDeviceCreated and buttonIconUpdated signals, and connect to the device in Component.onCompleted using connectStreamDeck with a 5x3 grid.

```qml
import QtQuick
import widgetbuilder.streamdeck

Item {
	id: root

	property string widgetId: "{widget-id-from-environment}"
	property string deviceId: "{streamdeck-device-id-from-environment}"

	StreamDeck {
		id: streamDeck

		onVirtualDeviceCreated: function(widgetId, deviceId) {
			// Handle initial virtual device creation
		}

		onButtonIconUpdated: function(widgetId, buttonIndex, iconDataUrl) {
			// Update button visuals in QML if needed
		}
	}

	Component.onCompleted: {
		streamDeck.connectStreamDeck(widgetId, deviceId, 5, 3);
	}

}
```

--------------------------------

### Complete example: translation.json

Source: https://docs.elgato.com/icue/widgets/references/translations

A complete translation file with English and Ukrainian translations for a clock widget.

```json
{
    "en": {
        "translation": {
            "Clock": "Clock",
            "Time Zone": "Time Zone",
            "Text Color": "Text Color",
            "Appearance": "Appearance"
        }
    },
    "uk": {
        "translation": {
            "Clock": "Годинник",
            "Time Zone": "Часовий пояс",
            "Text Color": "Колір тексту",
            "Appearance": "Зовнішній вигляд"
        }
    }
}
```

--------------------------------

### Directory Structure Example

Source: https://docs.elgato.com/icue/widgets/specification

Shows the recommended file layout for an iCUE widget, including required files and optional folders for modules, scripts, styles, and resources.

```text
mywidget/
├── index.html
├── manifest.json
├── translation.json
├── modules/
│   └── CitySearch.mjs
├── scripts/
│   └── widget.js
├── styles/
│   └── style.css
└── resources/
    ├── icon.png
    └── thumbnail.png
```

--------------------------------

### Minimal HTML Example

Source: https://docs.elgato.com/icue/widgets/specification

A minimal HTML widget structure with required head elements: title and icon link.

```html
<!doctype html>
<html lang="en">
	<head>
		<title>My Widget</title>
		<link rel="icon" type="image/x-icon" href="resources/icon.png" />
	</head>
	<body>
		<!-- Widget content -->
	</body>
</html>
```

--------------------------------

### Example lifecycle: slider control with refresh rate

Source: https://docs.elgato.com/icue/widgets/references/controls

Complete example showing how to define a slider control in the head, group it in a property group, and use the injected global variable in the widget script. The onICUEInitialized and onDataUpdated events are used to initialize and update the display. The refreshRate value is accessed directly and used to control a refresh loop.

```html
<head>
	<meta
		name="x-icue-property"
		content="refreshRate"
		data-label="Refresh Rate"
		data-type="slider"
		data-default="30"
		data-min="1"
		data-max="60"
		data-step="1"
		data-unit-label="'Hz'"
	/>

	<script type="application/json" id="x-icue-groups">
		[{ "title": "Settings", "properties": ["refreshRate"] }]
	</script>
</head>
<body>
	<div id="display"></div>
	<script>
		icueEvents = {
			onICUEInitialized: init,
			onDataUpdated: update,
		};

		function init() {
			update();
			startRefreshLoop();
		}

		function update() {
			// Access the current value
			document.getElementById("display").textContent = `Refresh: ${refreshRate}Hz`;
		}

		function startRefreshLoop() {
			setInterval(() => {
				// Use refreshRate value to control behavior
				fetchData();
			}, 1000 / refreshRate);
		}
	</script>
</body>
```

--------------------------------

### Basic Syntax: Static and Dynamic Meta Parameters

Source: https://docs.elgato.com/icue/widgets/references/javascript-expressions

Shows two meta tags: one with a static value and one with a dynamic expression. The dynamic example uses tr() and SystemUtils.getSystemVolume() to evaluate at runtime.

```html
<!-- Static value -->
<meta
	name="x-icue-property"
	content="brightness"
	data-label="'Brightness'"
	data-type="slider"
	data-default="50"
	data-min="0"
	data-max="100"
	data-step="1"
/>
<!-- Dynamic expression -->
<meta
	name="x-icue-property"
	content="brightness"
	data-label="tr('Brightness')"
	data-type="slider"
	data-default="SystemUtils.getSystemVolume()"
	data-min="0"
	data-max="100"
	data-step="1"
/>
```

--------------------------------

### Complete widget example - manifest

Source: https://docs.elgato.com/icue/widgets/references/controls/slider

Manifest JSON for a complete slider demo widget, specifying author, id, name, description, version, preview icon, minimum framework version, supported OS, and supported devices.

```json
{
  "author": "Corsair Team",
  "id": "com.corsair.sliderdemo",
  "name": "Slider Demo",
  "description": "Slider Demo",
  "version": "1.0.0",
  "preview_icon": "icon.png",
  "min_framework_version": "1.0.0",
  "os": [
    {
      "platform": "windows"
    },
    {
      "platform": "mac"
    }
  ],
  "supported_devices": [
    {
      "type": "dashboard_lcd",
      "features": ["sensor-screen"]
    },
    {
      "type": "pump_lcd"
    },
    {
      "type": "keyboard_lcd"
    }
  ]
}
```

--------------------------------

### Open link in system browser with fallback

Source: https://docs.elgato.com/icue/widgets/references/plugins/link-provider

Example usage in `index.html`. The `openLink` function checks for the plugin and calls `window.plugins.Linkprovider.open(url)`. If the plugin is not available (e.g., browser testing), it falls back to `window.open(url, '_blank')`.

```html
function openLink(url) {
    if (window.plugins && window.plugins.Linkprovider && pluginLinkprovider_initialized) {
        window.plugins.Linkprovider.open(url);
    } else {
        // Fallback for browser testing outside iCUE
        window.open(url, '_blank');
    }
}

openLink("https://www.corsair.com/ww/en");
```

--------------------------------

### Include local wrapper files

Source: https://docs.elgato.com/icue/widgets/references/plugins/media-data-provider

Copy common/plugins/ from the documentation bundle into your widget folder and include these scripts via local <script src> paths. Do not reference iCUE installation paths.

```html
<script src="common/plugins/IcueWidgetApiWrapper.js"></script>
<script src="common/plugins/SimpleMediaApiWrapper.js"></script>
```

--------------------------------

### Module File Structure: SystemUtils.mjs

Source: https://docs.elgato.com/icue/widgets/references/javascript-expressions

Example module file exporting functions for timezone, volume, and low light detection. Functions are exported using ES6 export syntax.

```javascript
export function getCurrentTimezone() {
	return Intl.DateTimeFormat().resolvedOptions().timeZone;
}
export function getAvailableTimezones() {
	return ["America/New_York", "Europe/London", "Europe/Kyiv", "Asia/Tokyo", "Australia/Sydney"];
}
export function getSystemVolume() {
	return 75;
}
export function isLowLightMode() {
	const hour = new Date().getHours();
	return hour < 7 || hour > 20;
}
```

--------------------------------

### media-selector meta tag example

Source: https://docs.elgato.com/icue/widgets/references/controls/media-selector

Defines a media-selector property for a background image with filters for PNG, JPG, and GIF files.

```html
<meta
    name="x-icue-property"
    content="backgroundImage"
    data-label="tr('Background Image')"
    data-type="media-selector"
    data-filters="['*.png', '*.jpg', '*.gif']"
/>
```

--------------------------------

### Plugin Functions: Manifest and HTML Example

Source: https://docs.elgato.com/icue/widgets/references/javascript-expressions

Shows the manifest requiring a plugin and an HTML meta tag using a plugin function. Only blocking (synchronous) functions are supported; asynchronous functions cannot be used.

```json
 "required_plugins": [
     "widgetbuilder.sensorsdataprovider:Sensors:1.0"
 ]
```

```html
<meta
	name="x-icue-property"
	content="selectedSensorId"
	data-label="'Sensor'"
	data-type="sensors-combobox"
	data-default="plugins.Sensorsdataprovider.getDefaultSensorIdBlock('temperature')"
/>
<!-- Only blocking (synchronous) functions are supported. Asynchronous functions cannot be used in meta parameter expressions. -->
```

--------------------------------

### Complete widget example - HTML

Source: https://docs.elgato.com/icue/widgets/references/controls/slider

HTML file for the complete slider demo widget. It includes the slider meta tag, a group definition, and JavaScript to update the displayed value.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>'Slider Demo'</title>
    <link rel="icon" type="image/svg+xml" href="resources/icon.svg">

    <meta name="x-icue-property" content="opacity"
          data-label="'Opacity'" data-type="slider"
          data-default="100" data-min="0" data-max="100" data-step="1" data-unit-label="'%'">

    <script type="application/json" id="x-icue-groups">
    [{"title": "'Settings'", "properties": ["opacity"]}]
    </script>
</head>
<body style="margin:0;height:100vh;display:flex;align-items:center;justify-content:center;background:#1a1a2e;color:#fff;font-family:sans-serif;">
    <div id="demo" style="font-size:48px;">100%</div>
    <script>
        icueEvents = { "onDataUpdated": update, "onICUEInitialized": update };
        function update() { document.getElementById("demo").textContent = opacity + "%"; }
        if (iCUE_initialized) update();
    </script>
</body>
</html>
```

--------------------------------

### Include required local wrapper files

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

Copy common/plugins/ from the documentation bundle into your widget folder and include these scripts via local <script src> paths. Do not reference iCUE installation paths in third-party widgets.

```html
<script src="common/plugins/IcueWidgetApiWrapper.js"></script>
<script src="common/plugins/SimpleSensorApiWrapper.js"></script>
```

--------------------------------

### Required local script includes for SimpleFpsApiWrapper

Source: https://docs.elgato.com/icue/widgets/references/plugins/fps-data-provider

Include these local wrapper files in your widget's HTML. Do not reference iCUE installation paths.

```html
<script src="common/plugins/IcueWidgetApiWrapper.js"></script>
<script src="common/plugins/SimpleFpsApiWrapper.js"></script>
```

--------------------------------

### Switch meta tag example

Source: https://docs.elgato.com/icue/widgets/references/controls/switch

Defines a switch property named 'showLabel' with a default value of true. The data-type is 'switch' and data-default is a boolean.

```html
<meta name="x-icue-property" content="showLabel"
      data-label="tr('Show Label')"
      data-type="switch"
      data-default="true">
```

--------------------------------

### Widget folder structure with common tools

Source: https://docs.elgato.com/icue/widgets/references/common-tools

Required folder layout for a widget that uses common tools. The `common` folder (or a specific tool subfolder) must be copied from `<<iCUE install dir>>/widgets/` into the widget root so relative references like `common/tools/media_viewer/MediaViewer.js` resolve alongside `index.html`.

```text
MyWidget/
├── index.html
├── manifest.json
└── common/
    └── tools/
        └── media_viewer/
            ├── MediaViewer.js
            └── MediaViewer.css
```

--------------------------------

### Async request pattern for getSensorValue

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

JavaScript example demonstrating the async request pattern: create a unique requestId, connect to the asyncResponse signal, and call getSensorValue. The response is logged when the requestId matches.

```javascript
let nextRequestId = 0;
const requestId = nextRequestId++;
window.plugins.Sensorsdataprovider.asyncResponse.connect((id, value) => {
    if (id === requestId) {
        console.log("Sensor value:", value);
    }
});
window.plugins.Sensorsdataprovider.getSensorValue(requestId, sensorId);
```

--------------------------------

### textfield widget HTML example

Source: https://docs.elgato.com/icue/widgets/references/controls/textfield

Shows how to define a textfield property in HTML using the x-icue-property meta tag with data-type="textfield" and data-default="'Hello World'". The data-default attribute sets the initial text value.

```html
<meta name="x-icue-property" content="title"
      data-label="tr('Title')"
      data-type="textfield"
      data-default="'Hello World'">
```

--------------------------------

### Initialize SimpleMediaApiWrapper

Source: https://docs.elgato.com/icue/widgets/references/plugins/media-data-provider

Create an instance of SimpleMediaApiWrapper by passing the plugin instance from window.plugins.Mediadataprovider. The wrapper converts the callback-based API into Promises.

```javascript
const api = new SimpleMediaApiWrapper(window.plugins.Mediadataprovider);
```

--------------------------------

### Package widget with icuewidget CLI

Source: https://docs.elgato.com/icue/widgets

Run from the terminal in the directory containing your widget files. Validates the widget structure and manifest, creates an .icuewidget package file, and displays a summary of the packaging process.

```bash
icuewidget package MyWidget
```

--------------------------------

### getCurrentProcess(requestId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/fps-data-provider

Gets the name of the current foreground process. The response is delivered via the asyncResponse signal with the matching requestId.

```APIDOC
## getCurrentProcess(requestId)

### Description
Gets the name of the current foreground process. The response is delivered via the asyncResponse signal with the matching requestId.

### Method
Async method (callback-based)

### Parameters
- **requestId** (int) - Required - Request ID used to correlate the response.

### Response
- **string** - Current foreground process name (file description from the executable)

### Example
```javascript
let nextRequestId = 0;
const requestId = nextRequestId++;
window.plugins.Fpsdataprovider.asyncResponse.connect((id, value) => {
	if (id === requestId) {
		console.log("Current process:", value);
	}
});
window.plugins.Fpsdataprovider.getCurrentProcess(requestId);
```
```

--------------------------------

### getCurrentFps(requestId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/fps-data-provider

Gets the current FPS value asynchronously. The response is delivered via the asyncResponse signal with the matching requestId.

```APIDOC
## getCurrentFps(requestId)

### Description
Gets the current FPS value asynchronously. The response is delivered via the asyncResponse signal with the matching requestId.

### Method
Async method (callback-based)

### Parameters
- **requestId** (int) - Required - Request ID used to correlate the response.

### Response
- **int** - Current frames per second

### Example
```javascript
let nextRequestId = 0;
const requestId = nextRequestId++;
window.plugins.Fpsdataprovider.asyncResponse.connect((id, value) => {
	if (id === requestId) {
		console.log("FPS value:", value);
	}
});
window.plugins.Fpsdataprovider.getCurrentFps(requestId);
```
```

--------------------------------

### getAllSensorIds(requestId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

Gets all available sensor identifiers asynchronously. The response is delivered via the asyncResponse signal with the matching requestId.

```APIDOC
## getAllSensorIds(requestId)

### Description
Gets all available sensor identifiers.

### Method
Asynchronous method call

### Parameters
- **requestId** (int) - Required - Request ID

### Response
- **sensorIds** (string[]) - Array of sensor identifiers
```

--------------------------------

### getSensorKind(requestId, sensorId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

Gets the sensor kind/category asynchronously. The response is delivered via the asyncResponse signal with the matching requestId.

```APIDOC
## getSensorKind(requestId, sensorId)

### Description
Gets sensor kind/category.

### Method
Asynchronous method call

### Parameters
- **requestId** (int) - Required - Request ID
- **sensorId** (string) - Required - Sensor identifier

### Response
- **kind** (string) - Sensor kind (see sensor kind)
```

--------------------------------

### getSensorType(requestId, sensorId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

Gets the sensor type asynchronously. The response is delivered via the asyncResponse signal with the matching requestId.

```APIDOC
## getSensorType(requestId, sensorId)

### Description
Gets sensor type.

### Method
Asynchronous method call

### Parameters
- **requestId** (int) - Required - Request ID
- **sensorId** (string) - Required - Sensor identifier

### Response
- **type** (string) - Sensor type (see sensor types)
```

--------------------------------

### Media plugin initialization callback

Source: https://docs.elgato.com/icue/widgets/references/plugins

Initialization callback for the Media plugin, using the module name Mediadataprovider.

```javascript
pluginMediadataproviderEvents = {
	onInitialized: onMediadataproviderInitialized,
};
```

--------------------------------

### Async request pattern for getCurrentProcess

Source: https://docs.elgato.com/icue/widgets/references/plugins/fps-data-provider

Example of retrieving the current foreground process name using the same async pattern with requestId and asyncResponse.

```javascript
let nextRequestId = 0;
const requestId = nextRequestId++;
window.plugins.Fpsdataprovider.asyncResponse.connect((id, value) => {
	if (id === requestId) {
		console.log("Current process:", value);
	}
});
window.plugins.Fpsdataprovider.getCurrentProcess(requestId);
```

--------------------------------

### getSensorName(requestId, sensorId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

Gets the sensor display name asynchronously. The response is delivered via the asyncResponse signal with the matching requestId.

```APIDOC
## getSensorName(requestId, sensorId)

### Description
Gets sensor display name.

### Method
Asynchronous method call

### Parameters
- **requestId** (int) - Required - Request ID
- **sensorId** (string) - Required - Sensor identifier

### Response
- **name** (string) - Sensor display name
```

--------------------------------

### getSensorUnits(requestId, sensorId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

Gets the units of measurement for a sensor asynchronously. The response is delivered via the asyncResponse signal with the matching requestId.

```APIDOC
## getSensorUnits(requestId, sensorId)

### Description
Gets units of measurement.

### Method
Asynchronous method call

### Parameters
- **requestId** (int) - Required - Request ID
- **sensorId** (string) - Required - Sensor identifier

### Response
- **units** (string) - Units of measurement (e.g., "C", "%", "RPM")
```

--------------------------------

### open(link)

Source: https://docs.elgato.com/icue/widgets/references/plugins/link-provider

Opens a link in the system browser. This method is available via window.plugins.Linkprovider.open(url) after the plugin is initialized.

```APIDOC
## open(link)

### Description
Opens a link in the system browser.

### Method
open

### Parameters
- **link** (string) - Required - Link to open

### Example
```javascript
function openLink(url) {
    if (window.plugins && window.plugins.Linkprovider && pluginLinkprovider_initialized) {
        window.plugins.Linkprovider.open(url);
    } else {
        // Fallback for browser testing outside iCUE
        window.open(url, '_blank');
    }
}

openLink("https://www.corsair.com/ww/en");
```
```

--------------------------------

### getSensorValue(requestId, sensorId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/sensors-data-provider

Gets the current sensor value asynchronously. The response is delivered via the asyncResponse signal with the matching requestId.

```APIDOC
## getSensorValue(requestId, sensorId)

### Description
Gets the current sensor value.

### Method
Asynchronous method call

### Parameters
- **requestId** (int) - Required - Request ID
- **sensorId** (string) - Required - Sensor identifier

### Response
- **value** (string) - The current sensor value
```

--------------------------------

### SimpleMediaApiWrapper

Source: https://docs.elgato.com/icue/widgets/references/plugins/media-data-provider

Promise-based wrapper for the Media plugin. Converts the callback-based Qt async API into Promises. Provides getSongName() and getArtist() methods that return Promises.

```APIDOC
## SimpleMediaApiWrapper

### Description
Promise-based wrapper for the Media plugin. Converts the callback-based Qt async API into Promises.

### Initialization
```
const api = new SimpleMediaApiWrapper(window.plugins.Mediadataprovider);
```

### Constructor Parameters
- **plugin** (object) - Required - Plugin instance (`window.plugins.Mediadataprovider`)
- **timeoutMs** (number) - Optional - Request timeout (ms), default `5000`

### Methods

#### getSongName()
Returns `Promise<string>` with the current song name.

#### getArtist()
Returns `Promise<string>` with the current artist name.

### Required local files
```
<script src="common/plugins/IcueWidgetApiWrapper.js"></script>
<script src="common/plugins/SimpleMediaApiWrapper.js"></script>
```

### Example
`manifest.json`
```
"required_plugins": [
  "widgetbuilder.mediadataprovider:Media:1.0"
]
```

`index.html`
```
// After including IcueWidgetApiWrapper and SimpleMediaApiWrapper in <head>:
const mediaApi = new SimpleMediaApiWrapper(window.plugins.Mediadataprovider);

async function displayCurrentTrack() {
    const [songName, artist] = await Promise.all([
        mediaApi.getSongName(),
        mediaApi.getArtist(),
    ]);
    console.log(`Now playing: ${songName} by ${artist}`);
}

// Playback controls (synchronous — call directly on the plugin)
window.plugins.Mediadataprovider.triggerPlayPause();
window.plugins.Mediadataprovider.triggerNextTrack();
window.plugins.Mediadataprovider.triggerPreviousTrack();
```
```

--------------------------------

### getArtist(requestId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/media-data-provider

Gets the current artist name asynchronously. The requestId is used for correlation, and the response is delivered via the asyncResponse signal.

```APIDOC
## getArtist(requestId)

### Description
Gets the current artist name asynchronously.

### Method
Plugin method

### Parameters
- **requestId** (int) - Required - Request ID for correlation

### Response
`string` - The current artist name
```

--------------------------------

### getSongName(requestId)

Source: https://docs.elgato.com/icue/widgets/references/plugins/media-data-provider

Gets the current song name asynchronously. The requestId is used for correlation, and the response is delivered via the asyncResponse signal.

```APIDOC
## getSongName(requestId)

### Description
Gets the current song name asynchronously.

### Method
Plugin method

### Parameters
- **requestId** (int) - Required - Request ID for correlation

### Response
`string` - The current song name
```

--------------------------------

### Switch usage in JavaScript

Source: https://docs.elgato.com/icue/widgets/references/controls/switch

Shows how to access the switch value in JavaScript. The variable 'showLabel' is a boolean, and the example uses it to control element visibility.

```javascript
console.log(showLabel); // true
element.style.display = showLabel ? "block" : "none";
```

--------------------------------

### Initialization Check

Source: https://docs.elgato.com/icue/widgets/references/plugins

Boolean variable indicating plugin load status.

```APIDOC
## Initialization Check

### Description
Boolean variable indicating plugin load status.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
```javascript
pluginSensorsdataprovider_initialized
pluginMediadataprovider_initialized
pluginLinkprovider_initialized
pluginFpsdataprovider_initialized
pluginDeviceactionprovider_initialized
```

### Response
N/A
```

--------------------------------

### Using tr() in JavaScript (async/await and Promise)

Source: https://docs.elgato.com/icue/widgets/references/translations

The tr() function returns a Promise. Shows both async/await and .then() usage to get translated strings.

```javascript
async function updateUI() {
    const label = await tr("Hello");
    document.getElementById("greeting").textContent = label;
}

tr("Settings").then((text) => {
    document.getElementById("title").textContent = text;
});
```
Tokens:
Raw