Skip to main content
Version: 2.1

wibox

wibox provides widgets, containers and layouts for bars, popups and other desktop UI.

Upstream documentation: awesomewm.org/apidoc/popups_and_bars/wibox.html

The animation reference covers frame transitions on wiboxes, popups and wibars, and property animations on their widgets.

Widget Types​

Widgets come in three categories: primitives that display content, containers that modify a single widget, and layouts that arrange multiple widgets. None of them draws or sizes itself: each declares what it holds and how it is sized, Clay calculates the output tree when layout is dirty, and SomeWM renders the result. Widgets in SomeWM 2.1 explains what each class declares, and Reading the tree maps the layouts and containers below onto the sizing words.

Primitives​

WidgetPurpose
wibox.widget.textboxDisplay text with optional markup
wibox.widget.imageboxDisplay images and icons
wibox.widget.progressbarHorizontal progress bars. Use a rotate container for vertical display
wibox.widget.sliderDraggable slider controls
wibox.widget.checkboxCheckboxes and toggle indicators
wibox.widget.graphLine/bar graphs for time series data
wibox.widget.systraySystem tray (SNI on Wayland)
wibox.widget.separatorVisual separator between widgets
wibox.widget.calendarCalendar display

Containers​

Containers wrap a single child widget to modify its appearance or size.

ContainerEffect
wibox.container.backgroundAdd background colour, foreground colour, shape, border. A childless background in a stack paints over the layers below.
wibox.container.marginAdd padding around a widget
wibox.container.constraintSet minimum/maximum size
wibox.container.placeAlign widget within available space (centre, left, etc.). A floating place keeps its whole allocation.
wibox.container.rotateRotate content (90, 180, 270 degrees). Text inside draws as one line. A scroll container inside, or a rotate inside a rotate, is left out with a warning
wibox.container.mirrorFlip content horizontally or vertically, with the same limits as rotate
wibox.container.scrollScroll content that overflows
wibox.container.radialprogressbarCircular progress indicator around a widget
wibox.container.arcchartArc-shaped chart around a widget

Layouts​

Layouts arrange multiple child widgets.

LayoutArrangement
wibox.layout.fixed.horizontalSide by side, each widget at its natural size
wibox.layout.fixed.verticalStacked vertically, each widget at its natural size
wibox.layout.flex.horizontalSide by side, all widgets equal width
wibox.layout.flex.verticalStacked vertically, all widgets equal height
wibox.layout.align.horizontalThree sections: left, centre, right
wibox.layout.align.verticalThree sections: top, centre, bottom
wibox.layout.stackAll children occupy the same space (overlapping)
wibox.layout.gridGrid with rows and columns. A non-homogeneous grid no longer sizes a column to the widest cell across rows. A widget added over another is refused. A row span occupies its first row and warns
wibox.layout.ratio.horizontalSide by side, proportional widths
wibox.layout.ratio.verticalStacked vertically, proportional heights
wibox.layout.manualAbsolute positioning

Custom widgets can compose these components, register a Clay description, or display a Cairo image surface. See Create or port a custom widget for examples.

Widget Composition​

Widgets compose by nesting. The widget field identifies the type, and children are table entries:

wibox.widget {
{
{
text = "Hello",
widget = wibox.widget.textbox,
},
margins = 8,
widget = wibox.container.margin,
},
bg = "#333333",
shape = gears.shape.rounded_rect,
widget = wibox.container.background,
}

Use id fields to access nested widgets later:

local w = wibox.widget {
{
id = "my_text",
text = "",
widget = wibox.widget.textbox,
},
widget = wibox.container.margin,
}

w:get_children_by_id("my_text")[1].text = "Updated"

References​

ReferenceDescription
Wibar PropertiesWibar positioning and configuration

Behavioural notes​

SomeWM uses the SNI (StatusNotifierItem) protocol for the system tray instead of X11's XEmbed. See Wayland vs X11 for details.

wibox.container.border is gone. Loading it is an error. Use wibox.container.background with border_width, border_color and shape. A widget class with its own fit, draw or layout method is left out of the tree with a warning. See Upgrading from 2.0 to 2.1.