Zebar 🦓

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

Installation • Intro • FAQ • Contributing ↗

⚙️ 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
• cpu
• date
• disk
• glazewm
• host
• ip
• keyboard
• komorebi
• media
• memory
• network
• weather

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
healthPercent	Condition of the battery as a percentage of perfect health. Returned value is between 0 to 100.	number
cycleCount	Number of charge/discharge cycles.	number
state	State of the battery.	'discharging' | 'charging' | 'full' | 'empty' | 'unknown'
isCharging	Whether the battery is in a charging state.	boolean
timeTillEmpty	Approximate time in milliseconds till battery is empty.	number | null
timeTillFull	Approximate time in milliseconds till battery is fully charged.	number | null
powerConsumption	Battery power consumption in watts.	number
voltage	Battery voltage.	number | null

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
usage	TODO	number
logicalCoreCount	TODO	number
physicalCoreCount	TODO	number
vendor	TODO	string

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
new	Current date/time as a JavaScript Date object. Uses new Date() under the hood.	Date
now	Current date/time as milliseconds since epoch. Uses Date.now() under the hood.	number
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

Disk

Config

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

Outputs

Variable	Description	Return type	Supported OS
disks	Available disks on the system.	Disk[]

Return types

Disk

Variable	Description	Return type
name	Disk name.	string | null
fileSystem	File system used on the disk (e.g. EXT4, NTFS).	string
mountPoint	Mount point of the disk (e.g. /, C:\\).	string
totalSpace	Total disk size.	DataSizeMeasure
availableSpace	Available disk size.	DataSizeMeasure
isRemovable	Whether the disk is removable.	boolean
driveType	Type of disk (e.g. HDD, SSD).	string

DataSizeMeasure

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

GlazeWM

Config

No config options.

Outputs

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

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

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
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
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
friendlyOsVersion	Friendly name of operating system version (eg. MacOS 13.2.1, Windows 10 Pro, Linux Debian GNU/Linux 9).	string | null
bootTime	Time when the system booted since UNIX epoch in milliseconds (eg. 1699452379304).	string
uptime	Time in milliseconds since boot.	string

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
approxCity	TODO	string
approxCountry	TODO	string
approxLatitude	TODO	number
approxLongitude	TODO	number

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
freeMemory	TODO	number
usedMemory	TODO	number
totalMemory	TODO	number
freeSwap	TODO	number
usedSwap	TODO	number
totalSwap	TODO	number

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
defaultGateway	TODO	Gateway
interfaces	TODO	NetworkInterface[]
traffic	Returns the network traffic per second.	NetworkTraffic

Return types

NetworkTraffic

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

DataSizeMeasure

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

Komorebi

Config

No config options.

Outputs

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

Media

Config

No config options.

Outputs

Variable	Description	Return type	Supported OS
session	Currently playing media session.	MediaSession | null

Return types

MediaSession

Variable	Description	Return type
title	TODO	string
artist	TODO	string | null
albumTitle	TODO	string | null
albumArtist	TODO	string | null
trackNumber	TODO	number
startTime	TODO	number
endTime	TODO	number
position	TODO	number
isPlaying	TODO	boolean

DataSizeMeasure

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
status	TODO	WeatherStatus
celsiusTemp	TODO	number
fahrenheitTemp	TODO	number
windSpeed	TODO	number