Quickstart (60 seconds) - Koya Documentation

Prerequisites #

Wayland compositor (Hyprland, Sway, Weston)
vulkan-icd-loader and Vulkan drivers
Koya binary (see Install): x86_64 or aarch64

Run your first bar #

Runtime API calls are asynchronous. In scripts, use async entrypoints and await for Helix/* and Koya/* operations.

Create the file in your config folder: ~/.config/koya/hello-bar.js

import * as Compositor from 'Koya/Compositor';
import * as UI from 'Helix/UserInterface';

export default async function ()
{
    const win = await Compositor.createWindow({
        role: 'bar',
        edge: 'top',
        thickness: 24,
        reserveSpace: true,
        namespace: 'hello-bar',
        keyboardInteractivity: 'none',
        acceptPointerEvents: false
    });

    await Compositor.setClearColor(win, 0.08, 0.09, 0.10, 0.3);

    const root = await UI.createElement(win, {
        layout: {
            type: 'row',
            wrap: false,
            gap: 8,
            padding: { t: 4, r: 8, b: 4, l: 8 },
            justifyContent: 'space-between',
            alignItems: 'center'
        }
    });
    await UI.attachRoot(win, root);

    const textId = await UI.createElement(win, {
        renderable: {
            type: 'text',
            string: 'hello koya',
            size: 14,
            colour: [1, 1, 1, 1],
            font: '/rom/fonts/SourceSans3-Regular.ttf'
        }
    });
    await UI.attach(win, root, textId);

    const boxId = await UI.createElement(win, {
        renderable: {
            type: 'box',
            aabb: { min: { x: 0, y: 0 }, max: { x: 22, y: 14 } },
            cornerRadius: 7,
            cornerResolution: 8,
            inset: 0,
            colour: [1, 1, 1, 1]
        }
    });
    await UI.attach(win, root, boxId);
}

Next steps #

Read Koya/Compositor for surface roles and multi-surface overlays.
Try custom shaders and shader parameters (see example below).
Browse real-world examples: - Plugins: Omnomios/helix-plugins - Waybar-like demo: Omnomios/koya-bar - Experimental Linux phone interface: Omnomios/koya-phone

import * as UI from 'Helix/UserInterface';

// Global per-window shader params (user0/user1 in shaders)
await UI.setShaderParams(win, { v0: [1, 0, 0, 0], v1: [0.25, 0.5, 0.75, 1.0] });

// At creation: attach custom shader and element params
const shaded = await UI.createElement(win, {
  renderable: {
    type: 'panel',
    texture: '/rom/arch.png',
    shader: { vert: '/rom/shaders/texture_only.vert.spv', frag: '/rom/shaders/texture_only.frag.spv' },
    shaderParams: { v0: [0.0, 1.0, 0.0, 0.0] }
  }
});
await UI.attach(win, root, shaded);

// Later: override per-element params
await UI.setElementShaderParams(win, shaded, { v1: [0.9, 0.2, 0.1, 0.0] });

<- Koya Install ->