adriankarlen / zebar

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

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.

🌟 Intro to Zebar

When Zebar is first launched, a set of default widget configs are generated to %userprofile%/.glzr/zebar. This includes various examples and templates to get you started with creating your own widgets.

To create a new widget, simply copy its config file into the %userprofile%/.glzr/zebar directory.

Widgets are powered by native webviews (similar to Electron, but less resource heavy). Every widget has its own config file and a corresponding HTML file for the markup and styling of the window. This is an ordinary HTML file, so any frontend framework (React, Angular, Vue, etc.) can be used.

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 (download).

🧩 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
• glazewm
• host
• ip
• keyboard
• komorebi
• 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

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[]
focusedMonitor	Monitor that currently has focus.	Monitor
currentMonitor	Monitor that is nearest to this Zebar window.	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.	number
transmitted	Transmitted bytes per second.	number

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 window.	KomorebiMonitor

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