Skip to content
/ zebar Public

Zebar is a tool for creating customizable and cross-platform taskbars, desktop widgets, and popups.

License

Notifications You must be signed in to change notification settings

glzr-io/zebar

Repository files navigation


Zebar logo

Zebar 🦓

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

Discord invite Good first issues

InstallationIntroFAQContributing ↗

zebar-demo

⚙️ Installation

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

For building locally, follow the instructions here.

🏁 Getting started

On first launch, Zebar generates some default widgets to %userprofile%/.glzr/zebar. This includes various examples and templates to get you started with creating your own widgets.

To create your own widget, a good way to start is by making a copy of one of the boilerplate configs created on first launch.

Widgets can be shared easily:

  1. Zip your widget configuration.
  2. Unzip it into the %userprofile%/.glzr/zebar directory.

🌟 Intro to Zebar

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

Each widget consists of:

  1. A config file (with a .zebar.json extension).
  2. An HTML file for markup and styling.

Any frontend framework can be used and boilerplates (e.g. for React, SolidJS) are included in the default widget configs.

Zebar exposes various system information (refered 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.

❓ 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 adminstrator.

🧩 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.

Battery

Config

Option Description Option type Default value
refreshInterval How often this provider refreshes in milliseconds. number 5000

Outputs

Variable Description Return type Supported OS
chargePercent Battery charge as a percentage of maximum capacity (aka. 'state of charge'). Returned value is between 0 to 100. number microsoft iconapple iconlinux icon
healthPercent Condition of the battery as a percentage of perfect health. Returned value is between 0 to 100. number microsoft iconapple iconlinux icon
cycleCount Number of charge/discharge cycles. number microsoft iconapple iconlinux icon
state State of the battery. 'discharging' | 'charging' | 'full' | 'empty' | 'unknown' microsoft iconapple iconlinux icon
isCharging Whether the battery is in a charging state. boolean microsoft iconapple iconlinux icon
timeTillEmpty Approximate time in milliseconds till battery is empty. number | null microsoft iconapple iconlinux icon
timeTillFull Approximate time in milliseconds till battery is fully charged. number | null microsoft iconapple iconlinux icon
powerConsumption Battery power consumption in watts. number microsoft iconapple iconlinux icon
voltage Battery voltage. number | null microsoft iconapple iconlinux icon

CPU

Config

Option Description Option type Default value
refreshInterval How often this provider refreshes in milliseconds. number 5000

Outputs

Variable Description Return type Supported OS
frequency TODO number microsoft iconapple iconlinux icon
usage TODO number microsoft iconapple iconlinux icon
logicalCoreCount TODO number microsoft iconapple iconlinux icon
physicalCoreCount TODO number microsoft iconapple iconlinux icon
vendor TODO string microsoft iconapple iconlinux icon

Date

Config

Option Description Option type Default value
formatting Formatting of the current date into a custom string format. Affects the output of formatted.

Refer to table of tokens for available date/time tokens.

Examples:

- 'yyyy LLL dd' -> 2023 Feb 13
- "HH 'hours and' mm 'minutes'" -> 20 hours and 55 minutes
string EEE d MMM t
timezone Either a UTC offset (eg. UTC+8) or an IANA timezone (eg. America/New_York). Affects the output of formatted.

A full list of available IANA timezones can be found here.
string local
locale An ISO-639-1 locale, which is either a 2-letter language code (eg. en) or a 4-letter language + country code (eg. en-gb). Affects the output of formatted.

A full list of ISO-639-1 locales can be found here.
string
refreshInterval How often this provider refreshes in milliseconds. number 1000

Outputs

Variable Description Return type Supported OS
formatted Current date/time as a formatted string. string microsoft iconapple iconlinux icon
new Current date/time as a JavaScript Date object. Uses new Date() under the hood. Date microsoft iconapple iconlinux icon
now Current date/time as milliseconds since epoch. Uses Date.now() under the hood. number microsoft iconapple iconlinux icon
iso Current date/time as an ISO-8601 string (eg. 2017-04-22T20:47:05.335-04:00). Uses date.toISOString() under the hood. string microsoft iconapple iconlinux icon

GlazeWM

Config

No config options.

Outputs

Variable Description Return type Supported OS
displayedWorkspace Workspace displayed on the current monitor. Workspace microsoft icon
focusedWorkspace Workspace that currently has focus (on any monitor). Workspace microsoft icon
currentWorkspaces Workspaces on the current monitor. Workspace[] microsoft icon
allWorkspaces Workspaces across all monitors. Workspace[] microsoft icon
allMonitors All monitors. Monitor[] microsoft icon
focusedMonitor Monitor that currently has focus. Monitor microsoft icon
currentMonitor Monitor that is nearest to this Zebar widget. Monitor microsoft icon
focusedContainer Container that currently has focus (on any monitor). Container microsoft icon
tilingDirection Tiling direction of the focused container. TilingDirection microsoft icon
bindingModes Active binding modes; BindingModeConfig[] microsoft icon
Function Description Return type Supported OS
runCommand Invokes a WM command.

Examples:

- runCommand("focus --workspace 1")
- runCommand("set-floating", containerId)

Parameters:

- command: string WM command to run (e.g. "focus --workspace 1").
- subjectContainerId: string | undefined (Optional) ID of container to use as subject. If not provided, this defaults to the currently focused container.
string microsoft icon

Host

Config

Option Description Option type Default value
refreshInterval How often this provider refreshes in milliseconds. number 60000

Outputs

Variable Description Return type Supported OS
hostname Name used to identify the device in various network-related activities. string | null microsoft iconapple iconlinux icon
osName Name of the operating system. This is Darwin on MacOS, Windows on Windows, or the Linux distro name retrieved from either /etc/os-release or /etc/lsb-release (eg. Debian GNU/Linux on Debian). string | null microsoft iconapple iconlinux icon
osVersion Operating system version. This is the version number on MacOS (eg. 13.2.1), the major version + build number on Windows (eg. 11 22000), or the Linux distro version retrieved from either /etc/os-release or /etc/lsb-release (eg. 9 on Debian 9). string | null microsoft iconapple iconlinux icon
friendlyOsVersion Friendly name of operating system version (eg. MacOS 13.2.1, Windows 10 Pro, Linux Debian GNU/Linux 9). string | null microsoft iconapple iconlinux icon
bootTime Time when the system booted since UNIX epoch in milliseconds (eg. 1699452379304). string microsoft iconapple iconlinux icon
uptime Time in milliseconds since boot. string microsoft iconapple iconlinux icon

IP

Config

Option Description Option type Default value
refreshInterval How often this provider refreshes in milliseconds. number 3600000

Outputs

Variable Description Return type Supported OS
address TODO string microsoft iconapple iconlinux icon
approxCity TODO string microsoft iconapple iconlinux icon
approxCountry TODO string microsoft iconapple iconlinux icon
approxLatitude TODO number microsoft iconapple iconlinux icon
approxLongitude TODO number microsoft iconapple iconlinux icon

Memory

Config

Option Description Option type Default value
refreshInterval How often this provider refreshes in milliseconds. number 5000

Outputs

Variable Description Return type Supported OS
usage TODO number microsoft iconapple iconlinux icon
freeMemory TODO number microsoft iconapple iconlinux icon
usedMemory TODO number microsoft iconapple iconlinux icon
totalMemory TODO number microsoft iconapple iconlinux icon
freeSwap TODO number microsoft iconapple iconlinux icon
usedSwap TODO number microsoft iconapple iconlinux icon
totalSwap TODO number microsoft iconapple iconlinux icon

Network

Config

Option Description Option type Default value
refreshInterval How often this provider refreshes in milliseconds. number 5000

Outputs

Variable Description Return type Supported OS
defaultInterface TODO NetworkInterface microsoft iconapple iconlinux icon
defaultGateway TODO Gateway microsoft iconapple iconlinux icon
interfaces TODO NetworkInterface[] microsoft iconapple iconlinux icon
traffic Returns the network traffic per second. NetworkTraffic microsoft iconapple iconlinux icon

Return types

NetworkTraffic

Variable Description Return type
received Received bytes per second. NetworkTrafficMeasure
transmitted Transmitted bytes per second. NetworkTrafficMeasure
totalReceived Total received bytes. NetworkTrafficMeasure
totalTransmitted Total transmitted bytes. NetworkTrafficMeasure

NetworkTrafficMeasure

Variable Description Return type
bytes Raw byte value. number
siValue Bytes converted in according to the SI standard. 1000 bytes in a kilobyte. number
siUnit Unit of the converted bytes in according to the SI standard. KB, MB, ... string
iecValue Bytes converted in according to the IEC standard. 1024 bytes in a kibibyte. number
iecUnit Unit of the converted bytes in according to the IEC standard. KiB, MiB, ... string

Keyboard

Config

Option Description Option type Default value
refreshInterval How often this provider refreshes in milliseconds. number 5000

Outputs

Variable Description Return type Supported OS
layout Current keyboard layout, for example 'en-US'. string microsoft icon

Komorebi

Config

No config options.

Outputs

Variable Description Return type Supported OS
displayedWorkspace Workspace displayed on the current monitor. KomorebiWorkspace microsoft icon
focusedWorkspace Workspace that currently has focus (on any monitor). KomorebiWorkspace microsoft icon
currentWorkspaces Workspaces on the current monitor. KomorebiWorkspace[] microsoft icon
allWorkspaces Workspaces across all monitors. KomorebiWorkspace[] microsoft icon
allMonitors All monitors. KomorebiMonitor[] microsoft icon
focusedMonitor Monitor that currently has focus. KomorebiMonitor microsoft icon
currentMonitor Monitor that is nearest to this Zebar widget. KomorebiMonitor microsoft icon

Weather

Config

Option Description Option type Default value
latitude Latitude to retrieve weather for. If not provided, latitude is instead estimated based on public IP. number | undefined undefined
longitude Longitude to retrieve weather for. If not provided, longitude is instead estimated based on public IP. number | undefined undefined
refreshInterval How often this provider refreshes in milliseconds. number 3600000

Outputs

Variable Description Return type Supported OS
isDaytime TODO string microsoft iconapple iconlinux icon
status TODO WeatherStatus microsoft iconapple iconlinux icon
celsiusTemp TODO number microsoft iconapple iconlinux icon
fahrenheitTemp TODO number microsoft iconapple iconlinux icon
windSpeed TODO number microsoft iconapple iconlinux icon