Overlay

Fission

Product

▾

Setup

›

›

Overlay is the two-layer stacking helper.

It renders content first, then renders overlay on top of that content while filling the same bounds. This is a strong fit for loading scrims, badges that should cover the same card, transient blocking layers, or other cases where you conceptually have a base surface plus one extra layer.

Use Overlay when the relationship is naturally "main thing plus one covering layer." Do not use it when you need many independently ordered layers or precise corner positioning. Those cases are clearer with ZStack and Positioned.

Example

use fission::prelude::*;
let widget: Widget = Overlay {
    content: Text::new("Invoice list").into(),
    overlay: 
        Container::new(Text::new("Syncing...").into())
            .bg(fission::core::op::Color {
                r: 0,
                g: 0,
                b: 0,
                a: 110,
            })
            .into(),
    ,
    ..Default::default()
}
.into();

Field table

Field	Type	Meaning	Notes / default behavior
id	Option<WidgetId>	Stable widget identity.	Defaults to None.
content	Widget	The base layer, drawn first.	Required. Default uses empty text widgets as placeholders.
overlay	Widget	The top layer, drawn above content.	Required. Internally wrapped in an absolute-fill layer.

Layout behavior

Overlay builds an internal stack. The overlay child is wrapped in an AbsoluteFill layout node so it covers the full bounds of the composed area, and the resulting stack is wrapped so it can stretch inside surrounding layouts.

That makes Overlay a practical high-level helper when the overlay should cover the same region rather than float at some independent position.

Specific advice

Use Overlay when the two-layer relationship itself is important to code readability. If the overlay needs a dismiss backdrop, focus trap, and multiple positioned children, step up to ZStack, FocusScope, and Positioned instead of trying to force everything through one overlay field.

Production checklist

For Overlay, review the fields that change behavior before treating the widget as finished: id, content, overlay. The goal is to make the product rule visible in state and actions, not hidden inside ad-hoc construction code.

•

If this widget appears inside an interactive flow, keep the surrounding action binding in the parent component and test that the flow still has one clear reducer path.

•

When child widgets are generated from data, give reordered or filtered rows an explicit WidgetId so retained local state and scroll behavior do not drift between items.

•

Set id only when identity must be stable across filtering, reordering, diagnostics, or tests; otherwise let Fission derive identity from structure.

•

Check the semantics tree for the user-facing label or role that makes this widget understandable without relying only on pixels.

•

Add at least one component or harness test that confirms the visible text, semantic role, action dispatch, and layout constraint that matter for this widget in context.

If a screen starts repeating the same Overlay setup, extract a named component around this widget. That keeps the reference API small while making product code easier to read and safer for generated code to copy.

ZStack, absolute_fill(...), and Positioned.