Skip to content

Modals

Use Modal as a normal child in your render tree. The modal declaration is layout-neutral, so it does not change parent layout, and its content is layered over the selected target when the open state is true.

use lurq::{
app::{component::Component, ctx::Ctx},
components::{Button, Column, Modal, Root, Text},
core::Signal,
node::Element,
};
struct App {
open: Signal<bool>,
}
impl Component for App {
type Props = ();
fn create(ctx: &mut Ctx) -> Self {
Self { open: ctx.signal(false) }
}
fn render(&self, _ctx: &mut Ctx) -> impl Into<Element> {
let open = self.open.clone();
Column::new()
.child(Button::new("Open modal").on_click({
let open = open.clone();
move |_| open.set(true)
}))
.child(
Modal::new(
Column::new()
.child(Text::new("Modal content"))
.child(Button::new("Close").on_click({
let open = open.clone();
move |_| open.set(false)
})),
)
.open(self.open.clone())
.target(Root),
)
}
}

Modal::target(...) accepts Parent, Root, or an ElementRef.

Modal::new(content).open(open.clone()).target(Parent);
Modal::new(content).open(open.clone()).target(Root);
Modal::new(content).open(open.clone()).target(panel_ref);
  • Parent covers the declaring parent bounds and is the default target.
  • Root covers the viewport. In a window that draws its own title bar it covers what is under the bar: a WindowChrome says how high its bar is, and the modal starts there, so that a dialog is centred in what is seen and nothing of it is under the bar. An overlay of the chrome itself (WindowChrome::overlay) has all of the window. An app that draws a title bar another way says its height with ctx.window().set_title_bar_inset(height).
  • ElementRef covers that element’s bounds.
  • When the signal is false, the modal declaration remains layout-neutral and no modal layer is rendered.
  • When the signal is true, the modal content is layered above its target.
  • Setting the signal back to false removes the modal on the next render pass. Content with an exit animation stays on screen, taking no input, until the animation ends: see Presence.
  • Open modals stack in the order they opened, as a browser’s top layer holds dialogs opened with showModal(): one opened over another is over it whatever their order in the tree, so a search declared in an app’s shell before the page opens over a dialog of the page. The topmost takes the pointer and Tab, Escape closes it first, and one that takes the focus gives it back into the modal under it as it closes. Modals that open in the same pass stack in the order they are declared.
  • Signal-backed modals close on Escape by default, wherever the focus is.
  • Modal::on_dismiss(handler) hears a person dismiss the modal: Escape, after the modal has set its signal to false. Content of the app’s that closes the modal for a person (a press on its veil, a close button) calls the same handler, as ui::Dialog, ui::Sheet, ui::Drawer and ui::CommandPalette do. The app setting the signal tells nothing. A second handler is called after the first.
  • An open modal traps Tab and Shift+Tab: they cycle the topmost modal’s stops (elements with tab_index(0) or higher, and form controls) and never reach the page behind it, with or without a form. A form inside the modal cycles inside it. See Modal Focus Trap.
  • Modal::takes_focus(true) moves the focus into the modal as it opens, to its first stop of Tab, and back to what had it as it closes, as a browser’s <dialog> opened with showModal() does. A focus the app or a press has put somewhere else by then stays there. The focus follows the last input’s modality, so a modal opened from the keyboard shows the ring on its first control. Off by default; ui::Dialog turns it on.

Added in lurq 0.61.0. A Sheet is content that comes up from the bottom of the window over everything in it, as a phone’s apps show a choice or a short task. It is a component of its own, mounted anywhere in the tree and taking no room there, and it is up while its signal is set:

use lurq::components::{Sheet, SheetDetent, SheetProps, SheetStyle};
let sheet = Sheet::mount(
ctx,
SheetProps::new(self.open.clone())
.detents([SheetDetent::Medium, SheetDetent::Large])
.style(SheetStyle::new().grabber(true)),
content,
);
  • It comes up and goes down with a move, a spring, and the window behind dims. It stays in the tree until it has gone down.
  • It is put away by clearing the signal, by Escape, by a press beside it, and by a finger that drags it down far enough or throws it down. SheetProps::dismissable(false) leaves only the signal. SheetProps::on_dismiss(handler) hears a person put it away (the drag, the press beside it, Escape), after its signal is false; clearing the signal tells nothing.
  • It stands at its detents: Content (as high as its content, the default), Medium (half the window), Large (the whole window under the status bar), Fraction(share) and Height(pixels). It comes up at the first, a finger moves it between them, and it goes to the nearest to where the finger threw it. SheetProps::detent(signal) says which it is at, by its place in the list, and sends it to another.
  • Its content is as high as what of the sheet is in the window, at a detent and between two: a content that fills the sheet (Column::new().size(FILL, FILL) with a list that takes the room and a bar under it) has its bar at the window’s bottom while a finger moves the sheet and on the way to the height it goes to. Pulled past its highest place the content is no higher, and the bar goes up with the sheet for as long as it is held; under its lowest the sheet is on its way out, and the content goes with it. A sheet as high as its content (Content) is as high as that.
  • Content that scrolls is named with SheetProps::scroll(state), the ScrollState of its list: a finger going up moves the sheet to its highest before the list scrolls, and one going down takes the sheet only when the list is at its top.
  • The content is clear of the home indicator and the keyboard: it is padded by the safe area, and the sheet rises by the keyboard’s height, as far as its highest place.
  • Like a Modal, it traps Tab.

Several sheets in one component are told apart with Sheet::mount_keyed.

Sheet::mount_with(ctx, props, |ctx| ..) makes the sheet’s content in the sheet, as a route’s is made in its outlet. What is mounted there is the sheet’s own: ctx.safe_area() is nothing inside it, since the sheet stands clear of the status bar and pads its content by the home indicator and the keyboard. That is what puts a StackOutlet’s bar at the sheet’s top:

let router = self.sheet_router.clone();
Sheet::mount_with(
ctx,
SheetProps::new(self.open.clone()).detents([SheetDetent::Large]),
move |ctx| Router::mount(ctx, router.clone()),
)

The router is the sheet’s own, made once with ctx.router(..), with a StackOutlet as its routes’ layout.

SheetStyle is how it looks and moves. Its colors come from the theme where it is made, light or dark as the theme is (Colors from the theme); ThemeDefinition::legacy() gives the white sheet over black at 0.3 of 0.62.

FieldStarts as
backgroundBackgroundThe sheet’s own color
corner_radius20Of its top corners
backdrop, dimScrim, 1What is drawn over the window behind, and how much of it shows
grabberfalseThe bar at the top that says it can be dragged
grabber_color, grabber_width, grabber_height, grabber_topInput, 36 by 5, 5 under the edge
top_margin10How far under the status bar the highest sheet stops
max_widthnoneIn a wider window the sheet stands in the middle
duration500 msOf every move
throw0.15How many seconds of a finger’s speed ahead the sheet is taken to be going

Behind a sheet at its full height a phone’s apps draw back: the app gets smaller, its top goes under the status bar’s room and its corners round. SheetHost around the whole of the app’s content does that, for every sheet mounted in the content. It makes its content itself, as a route’s is made in its outlet:

fn render(&self, ctx: &mut Ctx) -> impl Into<Element> {
let router = self.router.clone();
SheetHost::mount(ctx, move |ctx| Router::mount(ctx, router.clone()))
}

The app draws back as far as the sheet has come from its next height down, with the sheet and with the finger that has it. A sheet that never takes all the room only dims the app, and so does every sheet without a host. SheetHost::mount_with takes a SheetHostStyle: scale (0.92), corner_radius (12) and the background seen around the app (black).

A sheet that draws all of itself has a clear background, no corner_radius and no grabber: the content is then the whole sheet, and the moves, the heights and the finger are still the component’s.

Popup (and its alias Popover) layers content next to an anchor element. With a signal-backed open state it closes on Escape and on a left press outside it:

use lurq::components::{OutsidePress, Placement, Popup};
Popup::new(anchor_ref.clone(), menu_content)
.open(open.clone())
.placement(Placement::BottomStart);
// A light-dismiss popover: the closing press also reaches the element under it.
Popup::new(anchor_ref, hint_content)
.open(open.clone())
.outside_press(OutsidePress::PassThrough);

A popup or overlay is placed against its anchor’s layout in every frame, and turned to its anchor’s other side only where the window has no room on the side it asks for (Placement, with a collision that flips). One hung from an element of another layer, as a submenu from an item of its menu, is placed by that element as the layer draws it. It moves with the anchor when a list scrolls or the page lays out again. While its anchor is scrolled or clipped wholly out of view (above a scroll container’s viewport, under the header over a list, outside a clip()ped parent) it is not drawn, and it comes back with the anchor: it never floats over whatever covers the anchor. A Select’s menu does the same with its select, and a Modal targeting an element with that element. The open state does not change meanwhile, and a hidden popup is dismissed like a CSS popover that is out of view:

  • A left press anywhere closes it (with dismiss_on_outside_click, a Popup’s default). The press is never consumed by a hidden popup, whatever its outside_press: it also reaches the element it lands on, since nothing on screen was in its way.
  • Escape closes it (with dismiss_on_escape).
  • Keyboard focus inside it goes back to its anchor (the trigger) or the first focusable element inside the anchor; if the anchor holds none, to the nearest focusable ancestor of the anchor.

A tooltip without an open signal, such as a Markdown link’s, just stays hidden until its anchor is back in view.

A press is outside a popup when it lands neither on the popup, nor on its anchor, nor on a layer opened above it, such as a select menu or a popup opened from inside it. By default (OutsidePress::Consume) such a press only closes the popup, like a native menu: the element under the pointer receives no press, release or click, and focus does not move. The next press reaches it. This keeps a press meant to close a menu from also activating whatever lies under it, for example a tab, a list row or a button. OutsidePress::PassThrough closes the popup and delivers the press as usual, like a light-dismiss web popover; a handler that prevents the default of that press keeps the popup open.

Select menus follow the same rule, set with Select::outside_press(...). Overlay::outside_press(...) applies to overlays with dismiss_on_outside_click(true). A popup with dismiss_on_outside_click(false) or a static open state never closes on a press and never consumes one. Only left presses close popups; other buttons pass through and leave them open. When one press is outside several popups, it closes all of them, and it is consumed if any of them consumes it.

A press on another dropdown’s trigger is never consumed, like in a menu bar: it closes the open popup or select menu and goes on to that trigger, so one press opens the other dropdown and moves focus to its trigger. The first interactive element under the pointer (a button, a select, anything that takes focus) decides: it is a trigger when it is a Select, or the anchor itself of a popup (or overlay) with dismiss_on_outside_click(true) and a signal-backed open state, open or closed. Anything else inside an anchor is ordinary content: the other half of a split button anchored as a row, the items of a status bar that anchors a popover, and the bar’s empty space only close the open dropdown. The press closes the consuming popups and the open selects before it reaches the trigger, so a trigger that prevents the default of its press still switches. A press on a scrollbar over a trigger is not on the trigger. A press on the open popup’s own anchor is not outside it, so the anchor’s own handler decides (a toggle closes it, and a select menu open inside the popup closes too). Set switch_on_anchor_press(false) on a popup whose anchor a left press does not open, such as a context menu on a list row or an autocomplete list on a field. lurq only knows the anchor of a popup it can see: declare the popup always and drive it with its open signal, rather than adding it to the tree only while it is open, or a press on its anchor while another dropdown is open only closes that dropdown.

takes_focus(true) on a Popup (or an Overlay) moves the focus into it as it opens, to the first element in it that takes the focus, and gives the focus back as it closes with the focus inside: to what had it when the popup opened, where that is still in the tree, else to the anchor as above. While it is open its elements are in the order of Tab right after its anchor’s (see Tab Scope), and it keeps no Tab in it: it is not modal. A popup that is given another anchor while it is open, as the card of a tour goes from one element to the next, is the same popup: it does not take the focus again, which stays where it is in it, and as it closes the focus goes back to what had it before it first opened.

traps_tab(true) on a Popup (or an Overlay) holds Tab in it while the focus is in it, as a modal holds it: from its last element Tab goes to its first, and Shift+Tab from its first to its last, where it would go on to what follows its anchor. It is for what a person is to finish before going on and is still no modal, as the card of a tour (ui::Tour turns it on). It holds Tab and nothing else: the page behind answers the pointer, Escape and a press outside close the popup as its other settings say, and the focus goes back as takes_focus says. With the focus on the page Tab goes through the page, and into the popup after its anchor, where it is then held; the focus in a popup hung from an element of it, a menu’s, is in it too. A modal opened over it holds Tab itself, and with nothing in it that takes the focus Tab does nothing while the focus is in it. Off by default. Where the popup hangs from an element of another such popup that closes with it, as a submenu hangs from an item of its menu and an item of the submenu chosen closes both, the focus goes back from the outermost that closed: to what opened the menu. An app’s ctx.focus in the same pass wins. Off by default; ui::Popover and ui::Menu turn it on. Keep the anchor from one render to the next (a field of the component, ctx.element_ref()): one made anew in each render is not the one the focus goes back to.