On this page

Shadows and elevation

A soft shadow is one draw record, drawn by a closed form on every backend. Themes carry three elevations built from it, and any box can sit on one with style::lift.

Lifting a box

style::lift(elev) puts a box on one of the theme's elevations: elev_sm, elev_md or elev_lg. elev_none, the default, draws nothing. The drop is painted before the box, uses the box's corner radius and fades with the box's opacity. Text elements never take one.

cards.cpp
#include "isolenui/ui/ui.h"

// lift paints the theme's drop under the box, before the box itself, and fades
// with the box, a menu or card reads as raised with no paint code of its own
static void cards(ui::ctx* u)
{
    const ui::theme* t = ui::theme_of(u);
    ui_box(u, ui::row().gap(24.0f).pad(24.0f))
    {
        ui_box(u, ui::col().width(180.0f).pad(16.0f).bg(t->panel).round(t->radius).lift(ui::elev_sm))
        {
            ui::text(u, "resting", ui::body(u));
        }
        ui_box(u, ui::col().width(180.0f).pad(16.0f).bg(t->panel).round(t->radius).lift(ui::elev_md))
        {
            ui::text(u, "raised", ui::body(u));
        }
        ui_box(u, ui::col().width(180.0f).pad(16.0f).bg(t->menu).round(t->radius).lift(ui::elev_lg))
        {
            ui::text(u, "floating", ui::body(u));
        }
    }
}

// a theme can set its own elevations, one left all zero is still derived from bg
static ui::theme soft_theme(void)
{
    ui::theme t = ui::theme_hud();
    t.lift[ui::elev_md] = { { { 6.0f, 18.0f, -4.0f, 0x59000000u }, { 2.0f, 4.0f, -1.0f, 0x33000000u } } };
    ui::theme_lift(&t);
    return t;
}

A drop reaches past its box, the same way a focus ring does. The clip for it is widened by the furthest layer's reach, one and a half times its blur plus any positive spread plus its offset, so a lifted box flush with a clipping parent keeps its whole shadow. Only the drop is widened. The box and its children still clip as before.

Theme elevations

theme::lift[elev_count] holds one elevation per level. An elevation is two shadow_layers, each a CSS box shadow with no sideways offset: y, blur, spread and color. A layer whose colour is zero is skipped.

When a context takes a theme, at create or through set_theme, theme_lift fills every elevation left all zero. The values are Tailwind's shadow sm, md and lg. A light bg gets the light alphas, and a dark one about three times as much so the drop still reads.

LevelLayers, y blur spreadAlpha on lightAlpha on dark
elev_sm1 3 0, then 1 2 minus 126 and 2690 and 90
elev_md4 6 minus 1, then 2 4 minus 226 and 26100 and 90
elev_lg10 15 minus 3, then 4 6 minus 426 and 26130 and 100

The colour is always black at that alpha out of 255. The ground counts as light when its luma, 54 red, 183 green and 19 blue out of 256, is past half. Set a level yourself and it is kept as given. theme_lift is public, so a theme built by hand can be filled before it is handed over.

Which parts are lifted

LevelParts
elev_mdMenus of every kind, dropdowns, context menus, menubars and selects, the navigation menu panel, popovers, hover cards, tooltips, comboboxes, the combo list, the date and colour picker popups and the chart tooltip.
elev_lgDialogs, alert dialogs, message boxes, sheets, drawers, the command palette and toasts. A modal panel that already names a lift keeps its own.

These replaced the hard offset drops the kit drew before. See popovers, dialogs and toasts and menus.

Drawing one yourself

gfx_shadow(l, x, y, w, h, radius, blur, spread, rgba) records a soft shadow, and ui::drop(l, box, radius, elevation) records both layers of an elevation. Both are for canvas painters and raw lists. The numbers follow CSS box-shadow:

  • Offset. There is none. Move the box: y + 8 is an 8 unit drop.
  • Blur. The CSS blur radius. The Gaussian's sigma is half of it. A blur of 0.5 or less gives a hard edged shape.
  • Spread. Grows the box by that much on every side before the blur, and shrinks it when negative.
  • Radius. The corner radius of the box before spread. A rounded box's radius grows with the spread, as in CSS. A radius of zero stays square.
  • Colour. A packed colour with straight alpha, such as ui::rgb("#00000040") or ui::rgba(0, 0, 0, 0.25). A zero alpha, or a box that spread shrinks to nothing, records nothing.
tiles.cpp
#include "isolenui/gfx/gfx_list.h"
#include "isolenui/ui/ui.h"

// the same numbers as css box-shadow: 0 8px 24px -4px, the offset goes in the box
static void paint_tile(gfx_list* l, lay_box b, void*)
{
    gfx_shadow(l, b.x, b.y + 8.0f, b.w, b.h, 12.0f, 24.0f, -4.0f, 0x66000000u);
    gfx_round(l, b.x, b.y, b.w, b.h, 12.0f, 0xff1c1c22u);
}

// ui::drop paints both layers of an elevation, for a canvas that draws its own panel
static void paint_panel(gfx_list* l, lay_box b, void* user)
{
    const ui::theme* t = static_cast<const ui::theme*>(user);
    ui::drop(l, b, t->radius, t->lift[ui::elev_md]);
    gfx_round(l, b.x, b.y, b.w, b.h, t->radius, t->menu);
}

static void tiles(ui::ctx* u)
{
    ui::canvas(u, ui::row().width(220.0f).height(140.0f), paint_tile, nullptr);
    ui::canvas(u, ui::row().width(220.0f).height(140.0f), paint_panel,
               const_cast<ui::theme*>(ui::theme_of(u)));
}

How it is drawn

A shadow is a plain gfx_rect, not a new record kind. gfx_shadow_rect builds it: the box grows by the spread and then three sigma on every side, and border holds minus sigma. A negative border is what marks a rect as a shadow, so it culls, batches and damages like any other rect. gfx_round and gfx_outline now treat a negative border as zero, so they can never make one by accident.

  • Vulkan and Metal. The rect shader draws the blurred rounded box as one closed form per pixel, with an error function approximation and a superellipse corner. The per shadow terms are worked out once in the vertex stage.
  • CPU. The same closed form in SIMD. Rows inside the flat top of the blur take one span fill, and only corner rows pay for the curve.
A new backend draws shadows by honouring a negative border in its rect pass. See writing a backend.

Last updated 23 October 2026