Customize your interface

PluginUI gives you controls and interaction behavior for instrument and effect interfaces. You can change the palette, finish, typography and layout while keeping the same parameter bindings. Start with a working control, then change its appearance in the module's src/ui/ files.

Start with an existing control

Browse the component reference for knobs, faders, switches, meters and displays. Each entry includes a preview, props and source. The PluginUI examples show how these pieces form a complete interface.

Inside a Maru module, begin with a bound control:

import type { AudioModuleFaceProps } from "maruaudio/contracts"
import { FaceParamKnob } from "maruaudio/ui/module-face-controls"
import "./styles.css"

export default function MyFace(face: AudioModuleFaceProps) {
  return (
    <main className="my-module-face">
      <FaceParamKnob
        face={face}
        path="filter.cutoff"
        label="Cutoff"
        size={76}
        showLabelOnHover
      />
    </main>
  )
}

Declare filter.cutoff in your module schema first. Its range, default, unit and taper come from that descriptor. Layout and artwork belong in the face; parameter values and preset state stay with the host.

Scope your palette to the face

Controls read semantic CSS variables. Set them on your face wrapper so the surrounding application keeps its own appearance:

.my-module-face {
  --uikit-accent: #375e50;
  --uikit-surface: #f6f4ed;
  --uikit-text: #20251f;
  --uikit-text-muted: #566052;
  --uikit-focus: #375e50;
}

Check label contrast, focus rings and active states together. Choose component sizes and variants from the reference before overriding their internal styles. Use showLabelOnHover for a caption that shows the label at rest and the value while interacting.

Choose a finish

The themes and finishes guide explains shared control skins. Use the theme playground to compare a palette across several controls and export its CSS or recipe. Keep the palette and finish consistent across related controls.

For custom artwork, use the kit's headless controls and behavior hooks. Keep keyboard operation, focus, edit gestures and the stable parameter path when replacing a control's rendering. Module UI covers the face contract and porting an existing panel.

Preview the working module

Run maru dev <module-directory> and check pointer and keyboard edits, preset recall, narrow layouts and MIDI CC mapping. The sound and every visible readout should follow the same parameter when you change it from another input. Build your intended target before shipping to check the packaged styles, assets and dependencies too.