JSX Elements

Codegen generates a JSX element for each GObject class in the configured libraries, named after its GLib type, such as <GtkButton> or <AdwHeaderBar>. This page describes how element props map to the native API. Components covers the higher-level components built on them.

The JSX prop model

Generated elements follow the native API with GTKX naming conventions. This header bar toggles a search entry:

import type * as Gtk from "@gtkx/gi/gtk";
import { AdwHeaderBar, AdwToolbarView } from "@gtkx/jsx/adw";
import { GtkButton, GtkSearchEntry, GtkToggleButton } from "@gtkx/jsx/gtk";
import { useRef, useState } from "react";

export const SearchPane = () => {
    const [searching, setSearching] = useState(false);
    const entry = useRef<Gtk.SearchEntry>(null);

    return (
        <AdwToolbarView
            top={
                <AdwHeaderBar
                    start={
                        <GtkToggleButton
                            iconName="system-search-symbolic"
                            active={searching}
                            onNotifyActive={(active) => setSearching(active)}
                        />
                    }
                    end={
                        <GtkButton
                            label="Focus"
                            onClicked={() => entry.current?.grabFocus()}
                        />
                    }
                />
            }
        >
            <GtkSearchEntry
                ref={entry}
                sensitive={searching}
                onSearchChanged={(self) => console.log(self.getText())}
            />
        </AdwToolbarView>
    );
};

• Properties use camelCase, such as showTitleButtons.
• Signals use handler props, such as onClicked. GTKX passes the emitting object after the signal arguments.
• Property notifications use onNotifyX, receiving the new value and the emitting object.
• Object properties that accept elements can be expressed as JSX, with GTKX managing their lifetime. This includes construct-only ones, such as userContentManager={<WebKitUserContentManager onScriptMessageReceived={...} />} on a WebKitWebView: GTKX builds the prop's element first and passes its object when it constructs the parent, so the element must stay the same while the parent is mounted.
• Elements that show one child, such as GtkScrolledWindow, AdwClamp, window content or AdwToolbarView content, show the last one passed. Development builds warn when such an element holds more than one visible child; wrap them in a GtkBox.
• Child slots that no property backs are props named after their GtkBuilder child type, such as start and end on a header bar or top and bottom on a toolbar view.
• Refs expose the corresponding GI instance for imperative APIs.

A text prop on an editable widget, such as GtkEntry, or on a text buffer is written only when it differs from the widget's current text.

Handlers don't report what GTKX writes for you. Writing a prop doesn't call that property's onNotifyX handler, and signal handlers such as onChanged, onRowSelected or onClosePage stay quiet while a commit changes props or children.

Properties the widget changes in reaction still notify. When adding or removing children changes a property, such as the selected page after the selected tab is removed, its onNotifyX handler runs once the commit and its layout effects have finished, with the value at that point. The handler doesn't run when:

• The commit writes that property itself, as a controlled visibleChildName does.
• The property ends at the value its prop asks for, as a GtkDropDown's selected={0} does once its model is placed.
• The property ends at the value it had before the children changed.

A prop the element does not have, such as a typo, a C-style name like margin_top or a prop from another toolkit, throws an error that names the element and, where it can, the closest prop it does have.

Create objects and place children with JSX rather than through refs, so GTKX manages their lifetime. The generated element reference shows the exact props, slots, and signals for each configured library.

Member names

Native methods keep their generated camelCase names, even when a name overlaps a GTKX signal or property helper. For example, Gio.Socket.connect connects the socket; use GObject.signalConnect to connect one of its signals. When a method has the same name as a property, read and write the property with GObject.getProperty and GObject.setProperty from @gtkx/gi/gobject. Both take the camelCase property name and type the value from the object's properties.