Warp Settings Page Builder

gui-settings-ui

Scope — GUI desktop app only. This skill covers the settings modal in app/src/settings_view/, part of Warp's GUI desktop front-end. It does not apply to the headless TUI (crates/warp_tui). For general UI conventions see gui-ui-guidelines.

Settings pages look simple, so they get written by pattern-matching the nearest neighbor — and the nearest neighbor is often wrong. The same two mistakes have produced five Linear tickets (APP-5060, APP-5058, APP-4910, APP-4922, APP-5059, one of which turned out to be a false positive). Read this before writing a settings page so the sixth doesn't happen.

The model

A settings page is a PageType (app/src/settings_view/settings_page.rs). It holds a list of searchable widgets plus an optional page title:

PageType::new_uncategorized(widgets, Some("Knowledge"))
PageType::new_categorized(categories, None)
PageType::new_monolith(widget, Some("Billing and Usage"), /* is_dual_scrollable */ true)

• Uncategorized — a flat list of widgets. The common shape.
• Categorized — widgets grouped under Categorys, each with a subheader (rendered via render_sub_header) and an optional subtitle.
• Monolith — the whole page is a single widget because its content can't be split for search (Keybindings, Teams, About, Environments).

Each widget implements SettingsWidget (settings_page.rs):

• search_terms(&self) -> &str — the terms this widget matches on.
• render(..) — the widget's rows.
• should_render(&self, app) -> bool — defaults to true. This is one of two ways to conditionally show a setting, and usually not the right one — see "Two ways to gate a widget" below.
• widget_id() / static_widget_id() — default to std::any::type_name::<Self>(), used for scroll-to and deeplinks.

How search filters. PageType::update_filter keeps a widget when widget.should_render(app) && search_terms_match(widget.search_terms(), query). search_terms_match requires every whitespace-delimited word of the query to appear (case-insensitively, as a substring) somewhere in the widget's terms; an empty query matches everything. So filtering happens per widget — a widget is the smallest unit that can survive or disappear.

Whether the page title survives a search depends on the variant. PageType::render_page treats the title differently for widget-list pages than for a monolith, and that difference is the easiest thing here to get wrong.

For Uncategorized and Categorized, the title is drawn once, before the loop over the filtered widget list, unconditionally:

let mut page = Flex::column();
if let Some(title) = title {
    page.add_child(render_page_title(title, HEADER_FONT_SIZE, appearance));
}
for widget in widgets { /* … only the widgets that matched … */ }

The filter cannot reach it. That is what makes the title slot a fix for bug class 1: a title passed through PageType survives filtering on these two variants, while a title rendered inside a widget does not.

For Monolith, the title is gated on the sole widget surviving the filter:

FilteredPageType::Monolith { widget, title, .. } => {
    let mut page = Empty::new().finish();
    if let Some(widget) = widget          // None when the widget didn't match
        && widget.should_render(app)
    {
        if let Some(title) = title { /* … title, then the widget … */ }
    }
    page                                  // otherwise nothing renders at all
}

get_filtered sets that widget to filter.then_some(..), so a non-matching query makes it None and the page renders empty — title included. On a monolith the title slot buys no search protection; the page is all-or-nothing, title and all.

One more thing worth knowing before you go looking for a title stranded over zero rows: you won't find one. SettingsView::filtered_pages (app/src/settings_view/mod.rs) drops any page whose MatchData is falsy from the sidebar and auto-selects the first page that still matches, so a fully non-matching page is never displayed. The state the title slot actually protects is the partial match — some widgets survive, some don't — and only widget-list pages can be in it.

Two ways to gate a widget

There are two mechanisms for conditionally showing a setting, and they are not interchangeable.

1. An if at page-build time — never create the widget. This is how most gating in AISettingsPageView::build_page (ai_page.rs) is written:

if FeatureFlag::AIRules.is_enabled() {
    widgets.extend(Self::knowledge_widgets());
}
if cfg!(feature = "voice_input")
    && ai_settings.voice_input_enabled_internal.is_supported_on_current_platform()
{
    widgets.push(Box::new(VoiceWidget::default()));
}

2. should_render(&self, app) -> bool — create the widget and let it opt out per pass.

Which one: can the value change while the app is running?

• Fixed for the process — a feature flag, a cfg! feature, a platform-support check. → Use the build-time if. This is the preferred default: the widget never exists, so there is nothing to filter, render, or reason about.
• Can change at runtime — a setting the user toggles, auth state, an availability check that can flip mid-session. → Use should_render.

The reason is when each is evaluated. The build-time if runs once, when the page is constructed, and its result is frozen until something rebuilds the page (for AI/Code subpages, only switching subpages does — see below). should_render is re-evaluated on every filter and render pass, so it tracks a value that changes while the settings page is open. Gate a runtime-changing value with a build-time if and the page goes stale; gate a static flag with should_render and you carry a widget around for nothing.

The real should_render users are all the runtime kind: SettingsSyncWidget (main_page.rs) on auth state, WarpDriveToggleWidget (warp_drive_page.rs) on WarpDriveSettings::is_warp_drive_available, and the CLI-agent rich-input widgets (ai_page.rs) on the user-toggleable footer setting, via should_render_cli_agent_rich_input.

Either mechanism keeps search honest: an uncreated widget isn't in the list, and update_filter already skips a widget whose should_render is false. What you must never do is hide rows inside render while search_terms still advertises them — that makes the page match a query and then show nothing for it.

The decision that matters: where does the heading live?

For any heading on a settings page, ask what does it name?

• It names the whole page → it belongs in the PageType title slot. On Uncategorized / Categorized that is also what keeps it on screen while the page is filtered; on a Monolith it is a structural choice only (see above).
• It names one section among several → it belongs inside the widget (or Category) that owns that section, so it disappears together with its own rows.

Getting this wrong in the first direction is bug class 1 below. Getting it wrong in the second direction leaves a section header stranded above unrelated rows.

Page-shape taxonomy

Classify the page before you write it:

• Single-topic page — one heading names everything on it, but the content is still made of separately-matchable widgets. Knowledge, Third party CLI agents, Editor and Code Review, Account, Scripting. → Title in the PageType slot.
• Multi-section page — several independent sections, each with its own heading. Warp Agent, Agent profiles, Appearance, Features. → Per-section headings live in widgets/categories and correctly disappear with their rows. (For Categorized, get_filtered drops categories whose widgets all filtered out, so their subheaders vanish automatically — that's the behavior you want.)
• Monolith page — Keybindings, Teams, About, Environments, Codebase Indexing. There is no partial-match state: the sole widget either matches, and the whole page renders, or it doesn't, and the whole page renders empty and drops out of the sidebar. So a monolith can never strand an orphaned setting under a missing heading — it is not affected by bug class 1, but for that reason, not because its title is protected. Passing the title through the slot is still the tidier structure (Billing and Usage and Referrals do), just don't expect it to keep the title on screen during a non-matching search; on a monolith it will not. Codebase Indexing looks single-topic but is really one unfilterable widget covering the whole page (CodePageWidget, wrapped by CodeIndexingPageWidget) — building it as Uncategorized instead of Monolith made the sidebar show a permanent, misleading "(1)" on any match ([APP-5530]).

The two are not mutually exclusive: a page can name itself in the title slot and have per-section subheaders inside its widgets. Privacy does exactly that — PageType::new_uncategorized(widgets, Some("Privacy")) plus render_sub_header calls inside individual widgets. The rule is per heading, not per page.

Worked positive example: Scripting (scripting_page.rs) is a small page done right — two focused widgets (WarpControlCliInstallWidget, LocalControlModeWidget) with their own search_terms, and PageType::new_uncategorized(widgets, Some("Scripting")). A ticket was once filed claiming Scripting needed splitting; it was canceled because the premise was wrong. A small page is not automatically a mega-widget.