Ewwii - Widgets for everyone made better!

Ewwii (ElKowar's Wacky Widgets improved interface) is a foork of Eww (ElKowar's Wacky Widgets) which is a widget system made in Rust, which lets you create your own widgets similarly to how you can in AwesomeWM.

Strength of Ewwii over Eww:

• Full-fledged scripting & expressions
• User-defined widget trees & composition
• Built-in configuration libraries
• Builtin tooling for better developer experience
• Full control over reactive updates (user defines if widget should update dynamically)

Ewwii is configured in Rhai and themed using CSS or SCSS, it is easy to customize and is powerful and dynamic. The main goal of Ewwii is to make configuration easy and to give the user all the power that they need.

Rhai is not just a basic markup language. It is a full embeddable scripting language! This makes ewwii's configuration even more flexible and powerful.

Whether you're building a tiling-friendly status bar, a floating dashboard, or a themed control panel, Ewwii gives you the tools to design it, script it, and make it your own.

Getting Started

Getting starting with Ewwii. This section will cover how you can install and use ewwii.

Installation

The first step of using Ewwii is installing it. You would need to have the following prerequesties installed on your system to build/install ewwii.

Prerequesties:

• rustc
• cargo

Rather than with your system package manager, I strongly recommend installing it using rustup.

Additionally, eww requires some dynamic libraries to be available on your system. The exact names of the packages that provide these may differ depending on your distribution. The following list of package names should work for arch linux:

Note that you will most likely need the -devel variants of your distro's packages to be able to compile ewwii.

Building

Once you have the prerequisites ready, you're ready to install and build ewwii.

First clone the repo:

git clone https://github.com/Ewwii-sh/ewwii

cd ewwii

Then build:

cargo build --release --no-default-features --features x11

NOTE: When you're on Wayland, build with:

cargo build --release --no-default-features --features=wayland

Running ewwii

Once you've built it you can now run it by entering:

cd target/release

Then make the Eww binary executable:

chmod +x ./ewwii

Then to run it, enter:

./ewwii daemon
./ewwii open <window_name>

Installing via package managers

If you don't want to go through the very tedious task of cloning and building ewwii, you can install it using Cargo (Rust crate manager).

You can run the following command to install ewwii from cargo:

cargo install --git https://github.com/Ewwii-sh/ewwii

Optional: Statictranspl

Before diving deeper into Ewwii and Rhai (Ewwii’s configuration language), check out Statictranspl.

Rhai layouts are dynamic and can be verbose, which may feel overwhelming for users without experience in languages like Rust, C, or JavaScript. Statictranspl simplifies Rhai by abstracting much of the complexity, adding stricter compilation, and providing clearer error messages. Many issues can be caught at compile time, making it more beginner-friendly.

How it works: Statictranspl compiles a custom language called stpl into Rhai quickly and efficiently. For users creating static-only widgets, it can be a powerful way to simplify development.

Note: Statictranspl is experimental. It currently does not support most dynamic Rhai features, such as:

• Variables and updates
• Polling and listeners
• Functions and conditionals (if/else)
• Loops (for/while)
• Imports/exports

While excellent for static widgets, it cannot yet match the full flexibility of raw Rhai.

Configuration & Syntax

This section introduces the foundational systems that define how you configure your UI, express logic, and work with dynamic data in Rahi (Ewwii's configuration language).

The configuration model is imparative by nature but will be used in a declarative format that is made to make configuring ewwii easy as well as to provide a logical way of configuring. You'll also work with special built in functions and modules that expose live system state and other information.

We'll cover:

• The structure of configuration files
• Embedding expressions within properties and attributes
• Accessing and using built-in variables
• Interpolation, scoping, and reactivity rules

If you're coming from EWW's Yuck, expect similarities in structure but with much more flexibility and logical programming.

Writing your ewwii configuration

(For a list of all built-in widgets (i.e. box, label, button), see Widget Documentation.)
Ewwii is configured using its own language called rhai. Using rhai, you declare the structure and content of your widgets, the geometry, position, and behavior of any windows, as well as any state and data that will be used in your widgets. Rhai is based around imparative syntax, which you may know from programming languages like C, Rust etc. If you're using vim, you can make use of vim-rhai for editor support. If you're using VSCode, you can get syntax highlighting and formatting from vscode-rhai.

Additionally, any styles are defined in CSS or SCSS (which is mostly just slightly improved CSS syntax). While ewwii supports a significant portion of the CSS you know from the web, not everything is supported, as ewwii relies on GTK's own CSS engine. Notably, some animation features are unsupported, as well as most layout-related CSS properties such as flexbox, float, absolute position or width/height.

To get started, you'll need to create two files: ewwii.rhai and ewwii.scss (or ewwii.css, if you prefer). These files must be placed under $XDG_CONFIG_HOME/ewwii (this is most likely ~/.config/ewwii).

Now that those files are created, you can start writing your first widget!

Creating your first window

Firstly, you will need to create a top-level window. Here, you configure things such as the name, position, geometry, and content of your window.

Let's look at an example window definition:

enter([ // Add all defwindow inside enter. Enter is the root of the config.
  defwindow("example", #{
      monitor: 0,
      windowtype: "dock",
      stacking: "fg",
      wm_ignore: false,
      geometry: #{
        x: "0%",
        y: "2px",
        width: "90%",
        height: "30px",
        anchor: "top center"
      },
      reserve: #{ distance: "40px" side: "top" }
  }, label(#{ text: "example content" }))
])

Here, we are defining a window named example, which we then define a set of properties for. Additionally, we set the content of the window to be the text "example content".

You can now open your first window by running ewwii open example! Glorious!

defwindow-properties

monitor-property

This field can be:

• the string <primary>, in which case ewwii tries to identify the primary display (which may fail, especially on wayland)
• an integer, declaring the monitor index
• the name of the monitor
• a string containing a JSON-array of monitor matchers, such as: '["<primary>", "HDMI-A-1", "PHL 345B1C", 0]'. Ewwii will try to find a match in order, allowing you to specify fallbacks.

geometry-properties

X11

Wayland

Your first widget

While our bar is already looking great, it's a bit boring. Thus, let's add some actual content!

fn greeter(name) {
  return box(#{
    orientation: "horizontal",
    halign: "center"
  }, [
    button(#{ onclick: `notify-send 'Hello' 'Hello, ${name}'`, label: "Greet" })
  ]);
};

To show this, let's replace the text in our window definition with a call to this new widget:

enter([
  defwindow("example", #{
    // ... properties omitted
  }, greeter("Bob"))
])

There is a lot going on here, so let's step through this.

We are creating a function named greeter and a function is equal to a component that returns a child (widget). So function has two uses: one to return a component, and the other to do a set of functions. And this function takes one parameters, called name. The name parameter must be provided or else, you should emit it. Rhai does allow adding optional parameters, but we will talk about it later for the sake of beginners who are in-experienced with imprative programming languages.

Now inside the function, we declare the body of our widget that we are returning. We make use of a box, which we set a couple properties of.

We need this box, as a function can only ever contain a single widget - otherwise, ewwii would not know if it should align them vertically or horizontally, how it should space them, and so on. Thus, we wrap multiple children in a box. This box then contains a button. In that button's onclick property, we refer to the provided name using string-interpolation syntax: `${name}`. It is not possible to use a variable within a "" or '' just like javascript. You can learn more about it here.

To then use our widget, we call the function that provides the widget with the necessary parameters passed.

As you may have noticed, we are using a couple predefined widgets here. These are all listed and explained in the widgets chapter.

Rendering and Best Practices

Rendering children in your widgets

As your configuration grows, you might want to improve its structure by factoring out pieces into reusable functions.

In Ewwii’s Rhai-based configuration system, you can define wrapper functions that return widgets and accept a children parameter (or any parameter that you prefer), just like built-in widgets such as box() or button().

Here's an example of a custom container that adds a label before its children:

fn labeled_container(name, children = []) {
  return box(#{ class: "container" }, [label(#{text: name})] + children)
}

You can call it like this:

labeled_container("foo", [
  button(#{ onclick: "notify-send hey ho", label: "Click me" })
]);

Because children are just a list of widgets, you can also write functions that structure them however you'd like. For example, here's a layout that places the first two children side by side:

fn two_boxes(children = []) {
  return box(#{}, [
    box(#{ class: "first" }, [children[0]]),
    box(#{ class: "second" }, [children[1]])
  ]);
}

And call it like this:

two_boxes([
  label(#{ text: "First" }),
  label(#{ text: "Second" })
]);

If a child is missing (e.g., children[1] doesn't exist), make sure to handle that gracefully or document the expected number of children.

Window ID

In some cases you may want to use the same window configuration for multiple widgets, e.g. for multiple windows. This is where arguments and ids come in.

Firstly let us start off with ids. An id can be specified in the open command with --id, by default the id will be set to the name of the window configuration. These ids allow you to spawn multiple of the same windows. So for example you can do:

ewwii open my_bar --screen 0 --id primary
ewwii open my_bar --screen 1 --id secondary

Generating a list of widgets from array using for

If you want to display a list of values, you can use the for-Element to fill a container with a list of elements generated from a JSON-array.

let my_array = [1, 2, 3];

// Then, inside your widget, you can use
box(#{}, [
  for entry in my_array {
    button(#{ onclick: `notify-send 'click' 'button ${entry}'`, label: entry.to_string() })
  }
])

This can be useful in many situations, for example when generating a workspace list from an array representation of your workspaces. In many cases, this can be used instead of literal, and should most likely be preferred in those cases.

Splitting up your configuration

As time passes, your configuration might grow larger and larger. Luckily, you can easily split up your configuration into multiple files!

There are two options to achieve this:

Using import/export

// in ./foo/baz.rhai
fn greet() { return "Greetings!" }
export greet;

// in ./ewwii.rhai
import "foo/baz" as example;
print(example::greet()); // output: Greetings!

A rhai file may import the contents of any other rhai file that they export. For this, make use of the import directive. If you are exporting a variable/function, make use the export directive.

Using a separate ewwii configuration directory

If you want to separate different widgets even further, you can create a new ewwii config folder anywhere else. Then, you can tell ewwii to use that configuration directory by passing every command the --config /path/to/your/config/dir flag. Make sure to actually include this in all your ewwii calls, including ewwii kill, eww logs, etc. This launches a separate instance of the ewwii daemon that has separate logs and state from your main ewwii configuration.

ewwii --config "/path/to/your/config/dir"

Fundamentals

Ewwii uses Rhai as its configuration language. But instead of just pure Rhai, ewwii has its own layout that users should follow to create widgets using Rhai. And you may be wondering why ewwii has a "custom" layout instead of allowing users to just use pure Rhai. It's good question and the reason why ewwii has a custom layout is because it tries to remove unnecessary complexity.

The full reasons for this layout wont be explained much more because it goes way deeper than just "decreasing complexity".

For more information about Rhai, you can read their documentation.

Widgets and their parameters

Each widget in ewwii is a function (e.g: button(#{...}) is a function call to create a button). So each one requires its own parameters.

For example, defwindow expects a String, Properties, and a function call that returns a widget.

Example:

enter([
  // the string here (the text in "") is the name of the window
  // the content in #{} is the properties
  // and the 3rd `root_widget()` call is the function that returns a child.

  // defwindow cant have children in [] directly, but it expects a function returning it for it.
  defwindow("example", #{
      monitor: 0,
      windowtype: "dock",
      stacking: "fg",
      wm_ignore: false,
      geometry: #{
        x: "0%",
        y: "2px",
        width: "90%",
        height: "30px",
        anchor: "top center"
      },
      reserve: #{ distance: "40px" side: "top" }
  }, root_widget())
])

This is not that complex once you know the parameters of defwindow as most of the other widgets only take in properties or optinally children. Poll/Listen are the only things that is similar to defwindow and you will learn about it later in the variables chapter.

The root

It is an important concept that users must know to go forward with this documentaiton. Ewwii's Rhai layout is made to be logical and powerful, so the user is given access the root of the entire widget system.

The root is defined as enter() and it is where you should write defwindow.

Here is an example:

enter([
  defwindow("example", #{
      monitor: 0,
      windowtype: "dock",
      stacking: "fg",
      wm_ignore: false,
      geometry: #{
        x: "0%",
        y: "2px",
        width: "90%",
        height: "30px",
        anchor: "top center"
      },
      reserve: #{ distance: "40px" side: "top" }
  }, root_widget())
])

Now that you saw this example, you may be wondering why we are doing enter([]) instead of enter(). That is due to another fundamental concept in ewwii which is very important. You will learn about it in the properties and child definition section.

Semi-colons

Semi-colon is an important character in Rhai. Just like programming languages like JavaScript, Java, Rust etc.

You can use the following link to read about semi-colons in the Rhai book as they have an awesome documentation.

https://rhai.rs/book/ref/statements.html#statements

Properties and child definition

The part where most people get confused is the use of [] and #{}. Let's get into what those are and how you can use them.

The [] is used for adding children to a widget.

Example:

fn greeter(foo) {
  return box(#{
    orientation: "horizontal",
    halign: "center"
  }, [
    // the `[]` holds a button which is the child widget of the box widget
    // each element in a `[]` should end in a comma (,) instead of a semi-colon (;).
    button(#{ onclick: `notify-send '${foo}'`, label: "baz" }),
    label(#{ text: "example" }),
  ]);
};

The #{} works similar to the [] but, it is used to add properties into the widget.

Example:

fn greeter(foo) {
  // the `#{}` holds the properties of the box widget
  // each element in a `#{}` should end in a comma (,) instead of a semi-colon (;).
  return box(#{
    orientation: "horizontal",
    halign: "center"
  }, [
    // properties are assigned to both button and label using the #{}.
    button(#{ onclick: `notify-send '${foo}'`, label: "baz" }),
    label(#{ text: "example" }),
  ]);
};

Variables

Now that you feel sufficiently greeted by your bar, you may realize that showing data like the time and date might be even more useful than having a button that greets you.

To implement dynamic content in your widgets, you make use of variables.

All variables are only locally available so you would need to pass it around using function parameters. And whenever the variable changes, the value in the widget will update!

Static variables

In Rhai, all variables are dynamically typed bindings to values. You can define variables using let, pass them as function parameters.

Basic variables (let)

let foo = "value";

This is the simplest type of variable. Basic variables don't ever change automatically, if you need a dynamic variable, you can use built in functions like poll() and listen() to register dynamic values which we will talk about in the following section.

Dynamic variables

Just having static variables that wont update is pretty limiting. So, ewwii has two built in functions to register dynamic variables that can change according to the command.

Polling variables (poll)

poll("var_name", #{
  // It is recommended to have initial property passed.
  // If not provided, it will default to no value which may cause problems when used.
  // You can pass something like "" if you want no initial value.
  initial: "inital value",
  interval: "2s",
  cmd: "date +%H:%M:%S", // command to execute
})

A polling variable is a variable which runs a provided shell-script repeatedly, in a given interval.

This may be the most commonly used type of variable. They are useful to access any quickly retrieved value repeatedly, and thus are the perfect choice for showing your time, date, as well as other bits of information such as pending package updates, weather, and battery level. But it is important to note that these variables are locally available only in enter (a.k.a the root) and you need to pass it to other functions with something like some_fn(foo) when you want to use a polled variable.

To externally update a polling variable, ewwii update can be used like with basic variables to assign a value.

Listening variables (listen)

listen("foo", #{
  initial: "whatever",
  cmd: "tail -F /tmp/some_file",
})

Listening variables might be the most confusing of the bunch. A listening variable runs a script once, and reads its output continously. Whenever the script outputs a new line, the value will be updated to that new line. In the example given above, the value of foo will start out as "whatever", and will change whenever a new line is appended to /tmp/some_file.

These are particularly useful when you want to apply changes instantaneously when an operation happens if you have a script that can monitor some value on its own. Volume, brightness, workspaces that get added/removed at runtime, monitoring currently focused desktop/tag, etc. are the most common usecases of this type of variable. These are particularly efficient and should be preffered if possible.

For example, the command xprop -spy -root _NET_CURRENT_DESKTOP writes the currently focused desktop whenever it changes. Another example usecase is monitoring the currently playing song with playerctl: playerctl --follow metadata --format {{title}}.

Passing variables

As we discussed earlier, all variables are only available locally. So, you would need to pass it around from the current scope.

Here is an example of how it is done:

let foo = "example";

poll("time", #{
  initial: "inital value",
  interval: "2s",
  cmd: "date +%H:%M:%S",
})

// Here we have 2 variables named "time" (registered dynamically by poll) and foo (a static variable)

// here is an example of something that wont
fn wont_work() {
  return box(#{}, [ label(#{ text: time }), label(#{ text: foo }) ]);
}

dyn_id

dyn_id's are one of the most important properties of all. It is the property that decides if a widget should get updated dynamic or not.

dyn_id property is used to assign an id to a widget which the system will track to update if there is a change in property under the same id.

Example usage:

fn foo(foo_var) {
  return box(#{}, [
    label(#{ text: foo_var, dyn_id: "foo_var_user" }); // dyn_id used to make label dynamic
  ]);
}

enter([
  defpoll("foo", #{
    cmd: "echo baz",
    initial: "",
    interval: "1s"
  }),
  defwindow("bar", #{
    // .. properties omitted
  }, bar(foo)),
])

Here, when the variable foo changes, the text of label changes as well. If there is no dyn_id defined, then ewwii will ingore that change. But if it is defined with a unique value, then it will find the widget that is defined with the id that matches dyn_id and then update its text property which will result in a change in the UI.

The Rhai Expression Engine

Ewwii uses Rhai as its core expression and scripting engine. This means your configuration is more than just static values or simple substitutions—it’s real code, and you can use it anywhere dynamic behavior is needed.

Rhai expressions can:

• Perform logic and branching (if, match, ? :)
• Handle mathematical calculations and string operations
• Access nested data from arrays, maps, or JSON
• Run custom functions
• Be used directly in layout definitions, widget attributes, and style rules

Unlike Yuck, where expressions were embedded in { ... } or ${ ... }, Rhai treats expressions as native. They don’t need to be wrapped in special delimiters. If you can write it in Rhai, it just works.

Example

let value = 12 + foo * 10;

box(#{
  class: "baz"
  orientation: "h",
}, [
  button(#{
    class: button_active ? "active" : "inactive",
    on_click: "toggle_thing",
    label: `Some math: ${value}`,
  }),
]);

Core Features

Rhai supports a wide range of expression capabilities:

• Mathematics: +, -, *, /, %
• Comparisons: ==, !=, <, >, <=, >=
• Boolean logic: &&, ||, !
• Conditionals: if/else, ternary (cond ? a : b)
• Regex matching: =~ operator (Rust-style regex)
• Optional access: ?. and ?.[index]
• Data structures: maps/arrays (obj.field, arr[3], map["key"])
• Function calls: standard and Ewwii-specific built-ins (see below)
• String interpolation: `Value is ${value}` (standard Rhai feature)

Note

---

Rhai only allows string interpolation only for the strings that are quoted in `` similar to JavaScript.

Learn more about it here.

Common Built-in Functions

💡 You may recognize some of these from the old expression system—but now they're just Rhai functions.

Examples include:

• round(), floor(), ceil(), powi(), powf()
• min(), max(), sin(), cos(), etc.
• replace(), matches(), captures()
• strlength(), arraylength(), objectlength()
• jq() – run jaq-compatible filters on JSON data
• get_env() – read environment variables
• formattime() – format UNIX timestamps
• formatbytes() – format file sizes (IEC or SI)

Dynamic Usage

Because expressions are just Rhai, you can now write real logic inline or break it into reusable functions:

fn status_text(active) {
  return active ? "enabled" : "disabled";
}

label({
  text: `Status: ${status_text(system_active)}`
});

TL;DR

If you’ve used scripting languages like JavaScript or Lua, you’ll feel at home. Rhai gives you real control—not just interpolation tricks.

Theming & UI

This section focuses on visual styling and user interface customization. The core visual layer is built atop GTK, allowing deep integration with system themes while also enabling custom overrides through SCSS-style syntax.

We'll explore:

• How GTK theming works under the hood
• Styling your widgets using theme classes and custom CSS
• Layout implications of theme decisions (e.g., spacing, margins, z-order)

Whether you're trying to match your system's look or building a highly customized UI, this section gives you the tools to style confidently.

Working with GTK

Gtk Theming

Ewwii is styled in GTK CSS. You can use Vanilla CSS or SCSS to make theming even easier. The latter is compiled into CSS for you. If you don't know any way to style something check out the GTK CSS Overview wiki, the GTK CSS Properties Overview wiki , or use the GTK-Debugger.

If you have NO clue about how to do CSS, check out some online guides or tutorials.

SCSS is very close to CSS, so if you know CSS you'll have no problem learning SCSS.

GTK Debugger

The debugger can be used for a lot of things, especially if something doesn't work or isn't styled right.

To open the GTK debugger, simply run

eww inspector

If a style or something similar doesn't work, you can click on the icon in the top left to select the thing that isn't being styled correctly.

Then you can click on the drop down menu in the top right corner and select CSS Nodes. Here you will see everything about styling it, CSS Properties, and how it's structured.

Styling Widgets

Ewwii also allows writing inline styles to widgets using the style property. These styles are then applied at runtime using GTK's CSS system.

Example:

fn foo() {
    return box(#{
        style: "color: black; background-color: #fff;",
    }, [ label(#{ text: "baz" }) ]);
}

This example makes the text color of all child widgets of box to black and sets the background color of the box to white (#fff is the hexadecimal for white).

Modules

Modules undoubtedly are one of the most powerful features in Rhai. They provide infinite extensibility to ewwii.

Every module follows the syntax:

import "std::env" as env;
let home = env::get_home_dir(); // returns `$HOME` env var value

This allows you to write expressive, modular Rhai code with functions grouped logically under std or custom namespaces.

Standard Library

std::env

The std::env module provides access to common system-level environment queries. It is supported on Unix-based systems (Linux, macOS).

Usage

import "std::env" as env;

// Get an environment variable, or fallback to a default
let shell = env::get_env("SHELL") ?? "unknown";

// Set an environment variable (current process only)
env::set_env("DEBUG_MODE", "true");

// Get the user's home directory
let home = env::get_home_dir() ?? "/home/user";

// Get the current working directory
let cwd = env::get_current_dir() ?? "/";

// Get the current username
let user = env::get_username() ?? "nobody";

Functions

std::text

The std::text module provides access to more string manipulation that Rhai lacks.

Usage

import "std::text" as text;

// Convert a string to a URL-friendly slug
let slug = text::to_slug("Ewwii is cool!"); // output: "ewwii-is-cool"

// Convert a string to camelCase
let camel = text::to_camel_case("my cool project"); // output: "myCoolProject"

// Truncate a string to N characters (without splitting in the middle of a character)
let short = text::truncate_chars("hello world", 5); // output: "hello"

// Convert a string to uppercase
let upper = text::to_upper("hello"); // output: "HELLO"

// Convert a string to lowercase
let lower = text::to_lower("HELLO"); // output: "hello"

Functions

std::monitor

The std::monitor module provides utilities for querying information about connected monitors, including their resolution, dimensions, and DPI.

Usage

import "std::monitor" as monitor;

// Get number of monitors
let count = monitor::count(); // e.g., 2

// Get resolution of the primary monitor
let (w, h) = monitor::primary_resolution();
let res_str = monitor::primary_resolution_str(); // e.g., "1920x1080"

// Get resolutions of all monitors
let all_res = monitor::all_resolutions();
let all_res_str = monitor::all_resolutions_str(); // e.g., "1920x1080, 1280x1024"

// Get dimensions of a specific monitor
let (x, y, w, h) = monitor::dimensions(0);
let dim_str = monitor::dimensions_str(0); // e.g., "1920x1080"

// Get DPI of a monitor
let dpi = monitor::dpi(0);
let dpi_str = monitor::dpi_str(0); // e.g., "96.0"

Functions

Notes

• Monitor indices are zero-based: the primary monitor is index 0.
• DPI calculation assumes a base of 96 DPI multiplied by the monitor’s scale factor.
• The module automatically initializes GTK if it hasn’t been initialized on the main thread.

std::json

The std::json module provides utilities for working with JSON data within Rhai scripts. It allows parsing, serializing, and manipulating JSON objects dynamically.

Usage

import "std::json" as json;

// Parse a JSON string
let json_val = json::parse_json(r#"{"name":"Alice","age":30}"#);

// Convert JSON back to string
let json_str = json::to_string(json_val);

// Get a value from a JSON object
let name = json::get(json_val, "name"); // "Alice"

// Set a value in a JSON object
json::set(json_val, "age", 31);

Functions

Notes

• All JSON values are represented as Rhai Dynamic objects internally.
• Keys that do not exist in a JSON object return a UNIT value.
• set() only works on JSON objects; trying to set a key on a non-object JSON value will produce an error.
• Parsing and serialization errors are returned as Rhai EvalAltResult errors.

Future Plans

Other modules coming soon under std:

• std::fs — Filesystem operations (e.g., read_file, write_file, list_dir)
• std::path — Path helpers (e.g., join, basename, dirname)
• std::time — Time utilities (e.g., now, sleep, format_time)
• std::math — Numeric functions (e.g., clamp, lerp, map_range)
• std::color — Color parsing and manipulation (e.g., hex_to_rgb, blend)

You can easily extend or override these by adding .rhai modules in your config path.

API Library

api::wifi

The wifi module provides cross-platform Wi-Fi management for Linux and macOS systems. Functions include scanning networks, querying the current connection, connecting/disconnecting, and enabling/disabling the Wi-Fi adapter.

Note: macOS support is largely untested and may behave differently depending on system configuration.

Usage

import "api::wifi" as wifi;

// Scan for available networks
let networks = wifi::scan();

// Get current Wi-Fi connection info
let current = wifi::current_connection();

// Connect to a network
wifi::connect("MySSID", "MyPassword");

// Disconnect from the current network
wifi::disconnect();

// Enable/disable the Wi-Fi adapter
wifi::enable_adapter();
wifi::disable_adapter();

// Get adapter connection
wifi::get_adapter_connectivity();

Functions

Extra Notes

get_adapter_connectivity() has different outcome possibilities in each OS.

All possible results:

• Linux: "full" (internet available), "limited" (network only, no internet), "portal" (captive portal), "none" (no connectivity)
• macOS: "full" (connected to a Wi-Fi network) or "none" (not connected)

Platform Notes

• Linux: Uses nmcli for all operations. The module assumes nmcli is installed and accessible in $PATH.
• macOS: Uses /System/Library/PrivateFrameworks/Apple80211.framework/.../airport for scanning and disconnecting, and networksetup for connecting and enabling/disabling the adapter.
• Unsupported OS: All functions return an error if the platform is neither Linux nor macOS.

Returned Data Formats

• scan() (or scan_linux / scan_macos) returns an array of maps:

[
    { "ssid": "HomeWiFi", "signal": "78", "security": "WPA2" },
    { "ssid": "CafeNet", "signal": "65", "security": "WPA" }
]

• current_connection() returns a map:

{ "ssid": "HomeWiFi", "signal": "78", "security": "WPA2" }

Widgets

Widgets are the building blocks of your interface. Each widget represents a visual element—text, images, containers, interactive components—that can be composed, styled, and updated dynamically.

This section introduces:

• The basic anatomy of a widget definition
• How widgets are laid out within windows
• The attributes and properties available to each widget type
• Patterns for building reusable or dynamic widget trees

You’ll also learn how widget properties interact with the expression language and how reactivity is handled across updates.

Widgets & Parameters

Below is a list of available widgets and the parameters each accepts.

Widget Functions

These functions correspond to actual GTK widgets and render visible UI elements.

• box: props, children
• centerbox: props, children
• eventbox: props, children
• tooltip: children
• circular_progress: props
• graph: props
• transform: props
• slider: props
• progress: props
• image: props
• button: props
• label: props
• input: props
• calendar: props
• color_button: props
• expander: props, children
• color_chooser: props
• combo_box_text: props
• checkbox: props
• revealer: props, children
• scroll: props, children
• overlay: children
• stack: props, children

Utility Functions

These are not visible UI widgets but are essential for layout, data binding, or dynamic behavior.

• defwindow: string, props, children
• poll: props
• listen: props

Let's recall

---

props param: Defined in #{}

children param: Defined in []

Both of these are discussed in chapter 2.2

Widget Properties

widget

These properties apply to all widgets, and can be used anywhere!

Properties

• class: string css class name
• valign: string how to align this vertically. possible values: "fill", "baseline", "center", "start", "end"
• halign: string how to align this horizontally. possible values: "fill", "baseline", "center", "start", "end"
• vexpand: bool should this container expand vertically. Default: false
• hexpand: bool should this widget expand horizontally. Default: false
• width: int width of this element
• height: int height of this element
• active: bool If this widget can be interacted with
• tooltip: string tooltip text (on hover)
• visible: bool visibility of the widget
• style: string inline scss style applied to the widget
• css: string scss code applied to the widget

combo-box-text

Properties

• items: vec Items displayed in the combo box
• timeout: duration timeout of the command. Default: "200ms"
• onchange: string runs when an item is selected, replacing {} with the item

expander

Properties

• name: string name of the expander
• expanded: bool sets whether it's expanded

revealer

Properties

• transition: string animation name ("slideright", "slideleft", etc.)
• reveal: bool whether the child is revealed
• duration: duration how long the transition lasts. Default: "500ms"

checkbox

Properties

• checked: bool initial checked state
• timeout: duration command timeout. Default: "200ms"
• onchecked: string command when checked
• onunchecked: string command when unchecked

color-button

Properties

• use-alpha: bool use alpha channel
• onchange: string command on color select
• timeout: duration Default: "200ms"

color-chooser

Properties

• use-alpha: bool use alpha channel
• onchange: string command on color select
• timeout: duration Default: "200ms"

slider

Properties

• flipped: bool reverse direction
• marks: string draw marks
• draw-value: bool show value
• value-pos: string where to show value ("left", "right", etc.)
• round-digits: int number of decimal places
• value: float current value
• min: float minimum value
• max: float maximum value
• timeout: duration Default: "200ms"
• onchange: string command on change (use {} for value)
• orientation: string layout direction

progress

Properties

• flipped: bool reverse direction
• value: float progress (0–100)
• orientation: string layout direction

input

Properties

• value: string current text
• onchange: string command on change
• timeout: duration Default: "200ms"
• onaccept: string command on Enter
• password: bool obscure input

button

Properties

• timeout: duration Default: "200ms"
• onclick: string command on activation
• onmiddleclick: string command on middle click
• onrightclick: string command on right click

image

Properties

• path: string image file path
• image-width: int image width
• image-height: int image height
• preserve-aspect-ratio: bool keep aspect ratio
• fill-svg: string fill color for SVGs
• icon: string theme icon name
• icon-size: string size of the icon

box

Properties

• spacing: int spacing between children
• orientation: string direction of children
• space-evenly: bool distribute children evenly

overlay

Properties

None

tooltip

Properties

None listed

centerbox

Properties

• orientation: string direction of layout

scroll

Properties

• hscroll: bool allow horizontal scrolling
• vscroll: bool allow vertical scrolling

eventbox

Properties

• timeout: duration Default: "200ms"
• onscroll: string command on scroll ({} becomes direction)
• onhover: string command on hover
• onhoverlost: string command on hover exit
• cursor: string cursor type
• ondropped: string command on drop ({} is URI)
• dragvalue: string URI to drag from this widget
• dragtype: string type to drag ("file", "text")
• onclick: string command on click
• onmiddleclick: string command on middle click
• onrightclick: string command on right click

label

Properties

• text: string text to display
• truncate: bool truncate text
• limit-width: int max characters to show
• truncate-left: bool truncate beginning
• show-truncated: bool show truncation
• unindent: bool strip leading spaces
• markup: string Pango markup
• wrap: bool wrap text
• angle: float rotation angle
• gravity: string text gravity
• xalign: float horizontal alignment
• yalign: float vertical alignment
• justify: string text justification
• wrap-mode: string wrap mode ("word", "char", etc.)
• lines: int max lines (−1 = unlimited)

literal

Properties

• content: string raw yuck

calendar

Properties

• day: float selected day
• month: float selected month
• year: float selected year
• show-details: bool show details
• show-heading: bool show heading
• show-day-names: bool show day names
• show-week-numbers: bool show week numbers
• onclick: string command with {0}, {1}, {2} for day/month/year
• timeout: duration Default: "200ms"

stack

Properties

• selected: int child index
• transition: string animation name
• same-size: bool equal child size

transform

Properties

• rotate: float rotation angle
• transform-origin-x: string transform origin x
• transform-origin-y: string transform origin y
• translate-x: string shift x
• translate-y: string shift y
• scale-x: string scale x
• scale-y: string scale y

circular-progress

Properties

• value: float 0–100 progress
• start-at: float start percentage
• thickness: float line thickness
• clockwise: bool direction

graph

Properties

• value: float current value
• thickness: float line thickness
• time-range: duration duration to track
• min: float minimum value
• max: float maximum value

Examples

This section provides hands-on, practical demonstrations of everything covered so far. Real layouts, interactive components, and theming techniques will be used in these examples.

Each example is minimal but complete, focusing on a particular design pattern or technique. You can copy-paste them into your own config to experiment.

Included:

• Common layout patterns (e.g., bars, panels, dashboards)
• Interactive elements like buttons, sliders, toggles
• Theming techniques and tricks to override or enhance GTK styles

If you're stuck or just looking for inspiration, this is your go-to reference.

Starter Bar

A basic starter bar which will be very helpful to beginners, see examples/ewwii-bar.

Installing

This starter bar is installable via eiipm: ewwii's package manager.

Just run the following command and have the template ready in the current working directory in an instant!

eiipm i starter_template

Interactive Widgets

Theming Tricks

Troubleshooting

Here you will find help if something doesn't work. If the issue isn't listed here, please open an issue on the GitHub repo.

Ewwii does not compile

1. Make sure that you are compiling ewwii using a recent version of rust (run rustup update to be sure you have the latest version available)
2. Make sure you have all the necessary dependencies. If there are compile-errors, the compiler will tell you what you're missing.

Ewwii does not work on Wayland

1. Make sure you compiled ewwii with the --no-default-features --features=wayland flags.
2. Make sure that you're not trying to use X11-specific features (these are (hopefully) explicitly specified as such in the documentation).

My configuration is not loaded correctly

1. Make sure the ewwii.rhai and ewwii.(s)css files are in the correct places.
2. Sometimes, ewwii might fail to load your configuration as a result of a configuration error. Make sure your configuration is valid.

Something isn't styled correctly!

Check the GTK-Debugger to get more insight into what styles GTK is applying to which elements.

General issues

You should try the following things before opening an issue or doing more specialized troubleshooting:

• Kill the ewwii daemon by running ewwii kill and re-open your window with the --debug-flag to get additional log output.
• Now you can take a look at the logs by running ewwii logs.
• Use ewwii state to see the state of all variables.
• Use ewwii debug to see the structure of your widget and other information.
• Update to the latest ewwii version.
• Sometimes hot reloading doesn't work. In that case, you can make use of ewwii reload manually.

Remember, if your issue isn't listed here, open an issue on the GitHub repo.