Plugin API

Plugin API (v1)

Here all the functionality of the plugin api, all params are displayed

App

App = ({ config, setConfig }) => JSX

The App component is renderd on the screen when the plugin is selected, this should have all your config and setting the user can control.

name	Type	Description
config	object	The config you set by the setConfig function
setConfig	fn(Object)	Set any user config, merge the old config via ...config to prevent overwrites

Here a basic example

constApp=({ config, setConfig })=>{return(<div><labelhtmlFor="link">link: </label><inputname="link"onChange={(e)=>setConfig({ ...config,myLink: e.target.value})}value={config.myLink||""}/></div>)};exportdefaultApp;

---

manifest

manifest = Object

The manifest file will have all you plugin settings, used to tell webdeck how to consume this plugin.

name	Type	Description
version	number	(optional) The manifest version, current only 1 is available. If no value is provided, falls back to 1
icons	Object	(optional) Setup for you icons that will be used. "default" is required and is the default icon set
bespoke	boolean	(optional) If you plan to create a bespoke experience. Default drawing to key of icon/text/etc is disabled.

The basic manifest:

exportconstmanifest={version: 1,icons: {["default"]: {icon: ".....svg path string....",},},};

To add more icons, for example when user interacts with the plugin (e.g in this case turn on and off) you can provide additional icons.

exportconstmanifest={version: 1,icons: {["default"]: {icon: ".....svg path string....",},["on"]: {icon: ".....svg path string....",,},["off"]: {icon: ".....svg path string....",,},},};

---

init

init = (params) => function<destructor>

The init function is called when the plugin is initialized. The definition of initialized is "plugin is loaded AND used on a key". The function is called once per initialization, and a return function can be provided as a destruction. This pattern is very common in react-hooks.

exportconstinit=(params)=>{constinterval=setInterval(()=>{console.log("hello world every 1 second";},1000);return()=>clearInterval(interval)};

params

params: Object

name	Type	Description
drawkey	function<callback>	see draw function bellow
config	string	The configration
keyIndex	number	The current index of key this plugin is assigned

drawkey

drawkey : fn({ ctx, canvas}) => void

This function allows you to draw directly to the canvas:

exportconstinit=({ drawKey, config })=>{drawKey(({ ctx, canvas })=>{ctx.beginPath();ctx.arc(15,15,10,0,2*Math.PI);ctx.strokeStyle="yellow";ctx.stroke();});};

---

onPress

onPress = (params) => void

This function fire when user click the button, this is the main piece of code to trigger something to happen, you can put anything here to trigger. The most basic hello world example:

exportconstonPress=()=>{elsealert("hello world");};

params

params: Object

name	Type	Description
config	object	see config example bellow
icon	string	Icon string e.g "on" or "default"
keyIndex	number	The current index of key this plugin is assigned
plugin	string	Your plugin name as seen by webdeck
setIcon	fn(string)	see setIcon example bellow.
title	string	Subtitle given to you plugin.

config

config: Object

The config is an object, and value can be set via the App controller. Example:

exportconstonPress=({ config })=>{if(config.myText)alert(config.myText);elsealert("no text provided");};exportconstApp=({ config, setConfig })=>{return<inputonChange={(e)=>setConfig({myText: e.target.value})}value={config.myText||""}/>};

setIcon

setIcon: fn(string) => void

🟡 INFO- This requires icons to be configured in manifest first.

This function set an icon to display, usually based on a condition:

exportconstonPress=({ setIcon })=>{if(true)setIcon("on");};

---

onPressDown / onPressUp

Low‑level (optional) hooks for key‑down and key‑up. Same signature as onPress.

Primary use‑case: push‑to‑talk or hold‑for‑action keys.

---

Live‑preview pattern (optional)

If you want your key to redraw the moment the user edits a setting:

exportconstinit=({ drawKey })=>{constrender=()=>drawKey(({ ctx, canvas })=>{let{ color }=getConfig();ctx.clearRect(0,0,canvas.width,canvas.height);ctx.fillStyle=color;ctx.fillRect(0,0,canvas.width,canvas.height);});tick();// first paintconstid=setInterval(tick,1000);// repaint every secondwindow.addEventListener("webdeck:plugin-name:update",render);return()=>{// cleanupclearInterval(id);window.removeEventListener("webdeck-plugin-countdown:update",render);}}constApp=({ config, setConfig })=>{useEffect(()=>{window.dispatchEvent(newCustomEvent("webdeck:plugin-name:update"));},[config]);return(<div><labelhtmlFor="color">color: </label><inputtype="color"id="color"value={config.color||""}onChange={(e)=>setConfig({ ...config,color: e.target.value})}/></div>);};exportdefaultApp;