Feedback

Feedback widgets interrupt or annotate the current view to tell the user something: a toast slides a transient message over the content, while a dialog puts a modal surface in front of it and waits for a response. Adwaita draws them as real windows or floating sheets — a toast overlay layered above the page, an alert with a row of responses, the standard About window, a preferences sheet built from boxed lists.

Every widget below is described independently of any one toolkit, then shown three ways. Native GJS (real Libadwaita through @girs/adw-1) is the primary implementation; the Web (@gjsify/adwaita-web) and NativeScript (@gjsify/adwaita-nativescript) ports mirror it.

Note

The previews use the browser port, so each dialog is rendered in its open state and each toast in its visible state — natively these are real modal windows and transient overlays a user triggers, not steady content. Each preview is wrapped in a fixed-height stage so the overlay stays contained; a native window sizes and centres itself. Where a port diverges, its tab says so.

Toast

A toast is a transient notification — a short line of text, optionally with a single action button, that floats over the content for a few seconds and then dismisses itself. It is shown through a toast overlay that wraps the page and layers toasts above the bottom edge, so it never displaces the content beneath.

The overlay shows one toast at a time: adding a toast while another is visible queues it, and it appears only once the visible one is dismissed — by its timeout, its close button, its action button, or an explicit dismissal. All three ports share that queue: it lives in the headless @gjsify/adwaita-core layer, which the Web and NativeScript renderers compose.

Adw.Toast

TypeScript

import Adw from '@girs/adw-1';

// The overlay wraps the page content and floats toasts above it.
const overlay = new Adw.ToastOverlay({ child: content });

const toast = new Adw.Toast({
    title: 'File moved to Trash',
    timeout: 3,
    buttonLabel: 'Undo',
});
overlay.add_toast(toast);

Code

using Gtk 4.0;
using Adw 1;

// A toast is CONSTRUCTED, not declared — `Adw.ToastOverlay` is the part a
// blueprint carries, and `overlay.add_toast(...)` presents one at runtime.
Adw.ToastOverlay overlay {
  child: Adw.StatusPage {
    title: _("Documents");
    description: _("Drag files here to organise them.");
  };
}

HTML

<!-- import '@gjsify/adwaita-web' once to register the elements -->
<adw-toast-overlay id="overlay" style="width: 360px; height: 220px;">
    <adw-status-page title="Documents" description="Drag files here to organise them."></adw-status-page>
</adw-toast-overlay>

<script type="module">
    // Toasts are shown imperatively — the overlay floats them over its content.
    // The timeout is in seconds; a second toast added now would be queued and
    // shown once this one is dismissed.
    const overlay = document.getElementById('overlay');
    overlay.addToast('File moved to Trash', { timeout: 3, buttonLabel: 'Undo' });

    overlay.pendingToasts;  // how many are waiting behind the visible one
    overlay.dismiss();      // dismiss now and show the next queued toast
</script>

TypeScript

import { AdwToastOverlay } from '@gjsify/adwaita-nativescript';

const overlay = new AdwToastOverlay();
overlay.setContent(content);

// The NativeScript overlay timer is in milliseconds.
overlay.showToast('File moved to Trash', {
    timeout: 3000,
    buttonLabel: 'Undo',
});

Alert Dialog

An alert dialog is a modal message: a bold heading, some body text, and a row of responses the user must choose between. Each response is a button with a string ID; one may carry a destructive or suggested appearance, and a default and close response govern the Enter / Escape keys.

Adw.AlertDialog

TypeScript

import Adw from '@girs/adw-1';

const dialog = new Adw.AlertDialog({
    heading: 'Delete Project?',
    body: 'This will permanently remove the project and all of its files. This action cannot be undone.',
});

dialog.add_response('cancel', 'Cancel');
dialog.add_response('delete', 'Delete');
dialog.set_response_appearance('delete', Adw.ResponseAppearance.DESTRUCTIVE);
dialog.set_default_response('cancel');
dialog.set_close_response('cancel');

dialog.present(parent);

Code

using Gtk 4.0;
using Adw 1;

Adw.AlertDialog {
  heading: _("Delete Project?");
  body: _("This will permanently remove the project and all of its files. This action cannot be undone.");

  responses [
    cancel: _("Cancel"),
    delete: _("Delete") destructive,
  ]

  default-response: "cancel";
  close-response: "cancel";
}

HTML

<adw-alert-dialog
    open
    heading="Delete Project?"
    body="This will permanently remove the project and all of its files. This action cannot be undone."
>
    <adw-alert-response id="cancel">Cancel</adw-alert-response>
    <adw-alert-response id="delete" appearance="destructive">Delete</adw-alert-response>
</adw-alert-dialog>

TypeScript

import { AdwAlertDialog } from '@gjsify/adwaita-nativescript';

const dialog = new AdwAlertDialog(
    'Delete Project?',
    'This will permanently remove the project and all of its files. This action cannot be undone.',
);

dialog.addResponse('cancel', 'Cancel');
dialog.addResponse('delete', 'Delete');
dialog.defaultResponse = 'cancel';
dialog.closeResponse = 'cancel';

// NS substitutes the platform's native confirm() chrome; present() resolves
// to the chosen response ID.
const response = await dialog.present();

About Dialog

An about dialog is the standard application “About” window: a large app icon, the application name, a developer line and a version pill, with navigation into Details, Credits and Legal sub-pages built from the app metadata. It is the conventional destination of a primary-menu About entry.

Adw.AboutDialog

TypeScript

import Adw from '@girs/adw-1';
import Gtk from '@girs/gtk-4.0';

const dialog = new Adw.AboutDialog({
    applicationName: 'Adwaita Storybook',
    applicationIcon: 'application-x-executable-symbolic',
    developerName: 'A GJSify Project',
    version: '0.11.0',
    comments: 'A live catalogue of native GTK and Adwaita widgets, rendered under GJS.',
    website: 'https://github.com/gjsify/gjsify',
    issueUrl: 'https://github.com/gjsify/gjsify/issues',
    licenseType: Gtk.License.MIT_X11,
    developers: ['Ada Lovelace', 'Grace Hopper'],
    designers: ['Margaret Hamilton'],
    copyright: '© 2026 The GJSify Project',
});

dialog.present(parent);

Code

using Gtk 4.0;
using Adw 1;

Adw.AboutDialog {
  application-name: _("Adwaita Storybook");
  developer-name: _("A GJSify Project");
  version: "0.11.0";
  comments: _("A live catalogue of native GTK and Adwaita widgets, rendered under GJS.");
  website: "https://github.com/gjsify/gjsify";
  issue-url: "https://github.com/gjsify/gjsify/issues";
  license-type: mit_x11;
  copyright: "© 2026 The GJSify Project";
}

HTML

<!-- developers / designers are string arrays set as properties, e.g.
     el.developers = ['Ada Lovelace', 'Grace Hopper']; -->
<adw-about-dialog
    open
    application-name="Adwaita Storybook"
    developer-name="A GJSify Project"
    version="0.11.0"
    comments="A live catalogue of native GTK and Adwaita widgets, rendered under GJS."
    website="https://github.com/gjsify/gjsify"
    issue-url="https://github.com/gjsify/gjsify/issues"
    license="The MIT License (MIT)"
    copyright="© 2026 The GJSify Project"
></adw-about-dialog>

TypeScript

import { AdwAboutDialog } from '@gjsify/adwaita-nativescript';

const dialog = new AdwAboutDialog();
dialog.applicationName = 'Adwaita Storybook';
dialog.applicationIcon = '🗔';
dialog.version = '0.11.0';
// NS exposes only scalar fields — credits fold into the developer line.
dialog.developerName = 'A GJSify Project — Ada Lovelace, Grace Hopper';
dialog.comments = 'A live catalogue of native GTK and Adwaita widgets, rendered under GJS.';
dialog.website = 'https://github.com/gjsify/gjsify';
dialog.copyright = '© 2026 The GJSify Project';

dialog.present();

Preferences Dialog

A preferences dialog is a settings window organized into pages, each holding groups of boxed-list rows — switches, drop-downs, spin buttons. It is the multi-page container behind an application’s Preferences command; the common single-page case is shown here.

Adw.PreferencesDialog

TypeScript

import Adw from '@girs/adw-1';
import Gtk from '@girs/gtk-4.0';

const dialog = new Adw.PreferencesDialog();

const page = new Adw.PreferencesPage({
    title: 'General',
    iconName: 'preferences-system-symbolic',
});

const group = new Adw.PreferencesGroup({
    title: 'Appearance',
    description: 'Control how the application looks and behaves.',
});

group.add(new Adw.SwitchRow({ title: 'Dark style', subtitle: 'Use a dark colour scheme', active: true }));
group.add(new Adw.ComboRow({
    title: 'Accent colour',
    model: new Gtk.StringList({ strings: ['Blue', 'Teal', 'Green', 'Orange', 'Purple'] }),
    selected: 0,
}));
group.add(new Adw.SpinRow({
    title: 'Font size',
    adjustment: new Gtk.Adjustment({ lower: 8, upper: 24, value: 12, stepIncrement: 1 }),
}));

page.add(group);
dialog.add(page);
dialog.present(parent);

Code

using Gtk 4.0;
using Adw 1;

Adw.PreferencesDialog {
  title: _("Preferences");

  Adw.PreferencesPage {
    title: _("General");
    icon-name: "preferences-system-symbolic";

    Adw.PreferencesGroup {
      title: _("Appearance");
      description: _("Control how the application looks and behaves.");

      Adw.SwitchRow {
        title: _("Dark style");
        subtitle: _("Use a dark colour scheme");
        active: true;
      }

      Adw.ComboRow {
        title: _("Accent colour");
        selected: 0;

        model: Gtk.StringList {
          strings [_("Blue"), _("Teal"), _("Green"), _("Orange"), _("Purple")]
        };
      }

      Adw.SpinRow {
        title: _("Font size");

        adjustment: Gtk.Adjustment {
          lower: 8;
          upper: 24;
          value: 12;
          step-increment: 1;
        };
      }
    }
  }
}

HTML

<adw-preferences-dialog open title="Preferences">
    <adw-preferences-page title="General" icon-name="preferences-system-symbolic">
        <adw-preferences-group title="Appearance" description="Control how the application looks and behaves.">
            <adw-switch-row title="Dark style" subtitle="Use a dark colour scheme" active></adw-switch-row>
            <adw-combo-row title="Accent colour" items='["Blue","Teal","Green","Orange","Purple"]' selected="0"></adw-combo-row>
            <adw-spin-row title="Font size" min="8" max="24" value="12" step="1"></adw-spin-row>
        </adw-preferences-group>
    </adw-preferences-page>
</adw-preferences-dialog>

TypeScript

import {
    AdwPreferencesDialog,
    AdwPreferencesPage,
    AdwPreferencesGroup,
    AdwSwitchRow,
    AdwComboRow,
    AdwSpinRow,
} from '@gjsify/adwaita-nativescript';

const dialog = new AdwPreferencesDialog();
dialog.title = 'Preferences';

const page = new AdwPreferencesPage();
const group = new AdwPreferencesGroup();
group.title = 'Appearance';

const darkStyle = new AdwSwitchRow();
darkStyle.title = 'Dark style';
darkStyle.subtitle = 'Use a dark colour scheme';
darkStyle.active = true;
group.addRow(darkStyle);

const accent = new AdwComboRow();
accent.title = 'Accent colour';
accent.options = ['Blue', 'Teal', 'Green', 'Orange', 'Purple'].map((label) => ({ label, value: label }));
accent.selectedIndex = 0;
group.addRow(accent);

const fontSize = new AdwSpinRow();
fontSize.title = 'Font size';
fontSize.min = 8;
fontSize.max = 24;
fontSize.value = 12;
group.addRow(fontSize);

page.addGroup(group);
dialog.add(page);
dialog.present();

Related

• Boxed Lists — the preference rows a preferences dialog is built from.
• Presentation — the windows, header bars and views these overlays sit above.
• Adwaita Storybook — the same widgets in a live, interactive component browser.