<div align="center"> <br> <img src="https://github.com/user-attachments/assets/d1e10485-2cbb-4434-9d98-5c74702eebcc" width="350" alt="Zebar logo" /> <br>

Zebar 🦓

Zebar lets you create customizable and cross-platform desktop widgets.

[![Discord invite][discord-badge]][discord-link] [![Good first issues][issues-badge]][issues-link]

Installation • Intro • FAQ • Contributing ↗

</div>

⚙️ Installation

Downloads for Windows, MacOS, and Linux are available in the latest release.

For building locally, follow the instructions here.

🚀 Quick start

Accessing Zebar GUI

Click the Zebar icon in your system tray to open the GUI interface.

Installing widgets

Navigate to the marketplace within the GUI to browse and install widget packs.

Auto-starting widgets

Widgets can be set to run on startup by right clicking the Zebar tray icon then going to Widget packs -> <pack name> -> <widget name> -> Run on startup and clicking the widget name to check it.

🌟 Intro to Zebar

Widgets are powered by native webviews (similar to Electron, but more lightweight).

Creating your own widgets

Zebar looks within the ~/.glzr/zebar directory for directories containing a zpack.json file. Each zpack.json file defines a widget pack. Each widget pack can contain multiple widgets, each defined individually within the zpack.json file.

For example, a widget pack config could be located at ~/.glzr/zebar/example-widget/zpack.json, which would create a widget pack with an id of example-widget. Zebar only looks for zpack.json files one level deep within the ~/.glzr/zebar directory, so ~/glzr/zebar/example-widget/widget-1/zpack.json is invalid.

In the My widgets tab of the Zebar GUI, you can click Create new pack to generate a widget pack scaffold with the given name and description.

Within each widget pack, in the Widgets section you can click Add widget to create a new widget within that pack. When creating a new widget you can pick between some templates to get you started.

Apart from the React buildless template, other available templates require you to have Node.js and a package manager (npm/pnpm) installed. For these templates, run the build command (e.g. pnpm build) from the widget directory after any source code changes.

Modifying marketplace widgets

To edit a marketplace widget without fear of your changes being overridden, you should copy the folder from the marketplace directory (located at %AppData%/zebar/downloads/) to your own Zebar directory (located at ~/.glzr/zebar/).

DO NOT re-publish other peoples widgets without permission.

Advanced Customization

What is the zpack.json file?

Widgets are stored in packs, with each pack being defined by a zpack.json file. Each pack can contain multiple widgets, each individually defined within zpack.json.

Widgets consist of an HTML file, and any surrounding assets (e.g. CSS, JS, images, etc.).

The schema for zpack.json can be found here although all options can also be configured via the GUI.

Querying system information

Zebar exposes various system information (referred to as "providers") which can be used and displayed by your frontend. This includes stats like CPU usage, battery info, various window manager integrations, and lots more. See Providers for a list of available providers.

❓ FAQ

Q: Help! On Windows, Zebar is failing to start?

In some cases, updating to the latest Microsoft Webview2 version is needed (standalone download). Run the "Evergreen Standalone Installer" as administrator.

🧩 Providers

Through the zebar NPM package, Zebar exposes various system information via reactive "providers". Providers are a collection of functions and variables that can change over time.

• audio
• battery
• cpu
• date
• disk
• glazewm
• host
• ip
• keyboard
• komorebi
• media
• memory
• network
• systray
• weather

Audio

Config

No config options.

Outputs

| Variable | Description | Return type | Supported OS | | ------------------- | ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | defaultPlaybackDevice | Default audio playback device. | AudioDevice \| null | <img src="https://github.com/glzr-io/zebar/assets/34844898/568e90c8-cd32-49a5-a17f-ab233d41f1aa" alt="microsoft icon" width="24"> | | defaultRecordingDevice | Default audio recording device. | AudioDevice \| null | <img src="https://github.com/glzr-io/zebar/assets/34844898/568e90c8-cd32-49a5-a17f-ab233d41f1aa" alt="microsoft icon" width="24"> | | playbackDevices | All audio playback devices. | AudioDevice[] | <img src="https://github.com/glzr-io/zebar/assets/34844898/568e90c8-cd32-49a5-a17f-ab233d41f1aa" alt="microsoft icon" width="24"> | | recordingDevices | All audio recording devices. | AudioDevice[] | <img src="https://github.com/glzr-io/zebar/assets/34844898/568e90c8-cd32-49a5-a17f-ab233d41f1aa" alt="microsoft icon" width="24"> | | allDevices | All audio devices (both playback and recording). | AudioDevice[] | <img src="https://github.com/glzr-io/zebar/assets/34844898/568e90c8-cd32-49a5-a17f-ab233d41f1aa" alt="microsoft icon" width="24"> |

| Function | Description | Return type | Supported OS | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | setVolume | Sets the volume of an audio device. Changes the volume of the default playback device, unless SetVolumeOptions.deviceId is specified. <br><br> Parameters:<br> - volume: number Volume as a % of maximum volume. Returned value is between 0 and 100. <br> - options: SetVolumeOptions \| undefined Additional options.<br> | Promise<void> | <img src="https://github.com/glzr-io/zebar/assets/34844898/568e90c8-cd32-49a5-a17f-ab233d41f1aa" alt="microsoft icon" width="24"> |

Related types

AudioDevice

| Variable | Description | Return type | | ------------------ | ----------------------------- | ----------------------- | | deviceId | Device ID. | string | | name | Friendly display name of device. | string | | volume | Volume as a % of maximum volume. Returned value is between 0 and 100. | number | | type | Type of the device. | 'playback' \| 'recording' | | isDefaultPlayback | true if the device is selected as the default playback device.| boolean | | isDefaultRecording | true if the device is selected as the default recording device.| boolean |

SetVolumeOptions

| Variable | Description | Return type | | ------------------ | ----------------------------- | ----------------------- | | deviceId | Device ID to set the volume of. | string \| undefined |

Battery

Config

| Option | Description