README.md

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.

• 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
defaultRecordingDevice	Default audio recording device.	AudioDevice | null
playbackDevices	All audio playback devices.	AudioDevice[]
recordingDevices	All audio recording devices.	AudioDevice[]
allDevices	All audio devices (both playback and recording).	AudioDevice[]

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. Parameters: - volume: number Volume as a % of maximum volume. Returned value is between 0 and 100. - options: SetVolumeOptions | undefined Additional options.	Promise<void>

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	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[]

Related 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[]
isPaused	Whether the WM is paused.	boolean

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

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
currentSession	Currently playing media session.	MediaSession | null
allSessions	All active media sessions.	MediaSession[]

Function	Description	Return type	Supported OS
play	Plays the media session. Affects the current media session, unless MediaControlOptions.sessionId is specified. Parameters: options: MediaControlOptions | undefined Additional options.	Promise<void>
pause	Pauses the media session. Affects the current media session, unless MediaControlOptions.sessionId is specified. Parameters: options: MediaControlOptions | undefined Additional options.	Promise<void>
togglePlayPause	Toggles between playing/pausing the media session. Affects the current media session, unless MediaControlOptions.sessionId is specified. Parameters: options: MediaControlOptions | undefined Additional options.	Promise<void>
next	Skips to the next track. Affects the current media session, unless MediaControlOptions.sessionId is specified. Parameters: options: MediaControlOptions | undefined Additional options.	Promise<void>
previous	Skips to the previous track. Affects the current media session, unless MediaControlOptions.sessionId is specified. Parameters: options: MediaControlOptions | undefined Additional options.	Promise<void>

Related types

MediaSession

Variable	Description	Return type
sessionId	Unique identifier for the media session.	string
title	Title of the media session.	string
artist	Artist of the media session.	string | null
albumTitle	Album title of the media session.	string | null
albumArtist	Artist of the album (may differ from track artist).	string | null
trackNumber	Position of the track within its album.	number
startTime	Timestamp (in seconds) where playback begins.	number
endTime	Timestamp (in seconds) where playback ends.	number
position	Timestamp (in seconds) of current playback position.	number
isPlaying	Whether the media session is currently playing.	boolean
isCurrentSession	Whether this is the currently active session (i.e. currentSession).	boolean

MediaControlOptions

Variable	Description	Return type
sessionId	ID of the session to control. If undefined, the current session is used.	string | undefined

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

Related 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

Systray

Config

No config options.

Outputs

Variable	Description	Return type	Supported OS
icons	All Windows taskbar system tray icons.	SystrayIcon[]

Related Types

SystrayIcon

Variable	Description	Return type
id	ID of the icon.	string
iconBytes	Icon pixel array.	number[]
iconBlob	Icon in memory.	Blob
iconUrl	Icon URL ready to be be referenced in <img> components.	string

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