Skip to main content
Version: 2.2 (dev)

Wibar properties

awful.wibar attaches a wibox to a screen edge. By default it reserves workarea space, so tiled clients do not cover it. Constructor arguments override beautiful.wibar_* theme values.

Basic Properties​

PropertyTypeDefaultDescription
positionstring"top"Bar position: "top", "bottom", "left", "right"
screenscreen/number1Screen to attach the wibar to
heightnumberTheme or font-basedThickness for top/bottom bars
widthnumberTheme or font-basedThickness for left/right bars
stretchbooleantrue unless length is specifiedFill the screen edge
alignstring"centered"Alignment when not stretched: "left", "right", "top", "bottom", or "centered"
restrict_workareabooleantrueReserve space when visible and not ontop
visiblebooleantrueWhether the wibar is visible
ontopbooleanbeautiful.wibar_ontop or falseDraw above ordinary clients without reserving workarea
animationtable/booleannilVisibility transitions. See Animation

Appearance​

PropertyTypeDefaultDescription
bgcolorbeautiful.wibar_bgBackground color
fgcolorbeautiful.wibar_fgForeground/text color
bgimagesurface/stringbeautiful.wibar_bgimageBackground image, drawn over bg. See Background Image
opacitynumberbeautiful.wibar_opacity or 1Applies to each fill separately. Overlapping fills accumulate opacity
shapefunctionbeautiful.wibar_shapeShape function (e.g., gears.shape.rounded_rect)

Borders​

PropertyTypeDefaultDescription
border_widthnumberbeautiful.wibar_border_width or 0Border width in pixels
border_colorcolorbeautiful.wibar_border_colorBorder color

Margins​

PropertyTypeDefaultDescription
marginstable/numberbeautiful.wibar_margins or 0Margins around the wibar

Margins can be a number (all sides) or a table:

local margins = {
top = 8,
bottom = 0,
left = 8,
right = 8,
}

Content​

PropertyTypeDefaultDescription
widgetwidget-The widget tree to display

If no thickness is supplied by the arguments or theme, it is ceil(1.5 * beautiful.get_font_height(font)). A horizontal bar’s width or a vertical bar’s height sets its length and disables stretching by default. At construction, length can be a percentage string when screen is explicitly supplied.

Examples​

Basic Wibar​

local awful = require("awful")
local wibox = require("wibox")

local bar = awful.wibar {
screen = screen.primary,
position = "top",
height = 32,
widget = wibox.widget.textclock(),
}

Floating Wibar​

margins = 8 leaves space around the bar. A shape changes its outline. See the wibar tutorial for composition examples.

Transparent Wibar​

Use a colour with alpha, such as bg = "#222222cc", or set opacity to affect all its fills. Overlapping fills blend separately in 2.1. Appending alpha to an arbitrary theme value is unsafe because colours can already include alpha or be Cairo patterns.

Vertical Sidebar​

Use position = "left" or "right" and specify width for thickness.

Controlling Visibility​

bar.visible = not bar.visible

Changing visible schedules layout. Clay then updates the reserved workarea and queues property::workarea. A read immediately after the assignment can still return the old workarea.

Background Image​

bgimage paints an image on top of the background color. It accepts these values:

ValueBehavior
File path (string)Loaded with gears.surface and cached. A bad path is not an error: it logs a message and draws nothing
Cairo surfaceUsed as-is
FunctionUnsupported. Warns and clears the image

A path or surface is painted once at native size, from the top-left corner. It is neither tiled nor stretched. The remaining area shows bg.

beautiful.wibar_bgimage is read at construction when no explicit bgimage is supplied. Later changes require assigning bar.bgimage. The property is write-only in 2.1.

See wibar background images for tiled and stretched images.

Theme Variables​

These beautiful variables provide defaults for wibars:

VariableDescription
wibar_bgDefault background
wibar_fgDefault foreground
wibar_bgimageDefault background image (surface or path)
wibar_height, wibar_widthDefault dimensions
wibar_shape, wibar_opacityShape and opacity
wibar_ontop, wibar_type, wibar_cursorStacking, window type and pointer cursor
wibar_fontFont used to calculate default thickness
wibar_margins, wibar_align, wibar_stretchPlacement
wibar_shadowShadow override
wibar_border_colorDefault border color
wibar_border_widthDefault border width

See Also​