GTKX lets you build native Linux desktop applications using React and TypeScript. Write familiar React code that renders as native GTK4 widgets—no Electron, no web views.

Features

• React — Hooks, state, props, and components you already know
• Hot Reload — Edit code and see changes instantly via Vite
• Native — Direct FFI bindings to GTK4 via Rust and libffi
• CLI — npx @gtkx/cli@latest create scaffolds a ready-to-go project
• CSS-in-JS — Emotion-style css template literals for GTK styling
• Testing — Testing Library-style screen, userEvent, and queries

Quick Start

npx @gtkx/cli@latest create my-app
cd my-app
npm run dev

Edit your code and see changes instantly—no restart needed.

Example

import {
  render,
  ApplicationWindow,
  Box,
  Button,
  Label,
  quit,
} from "@gtkx/react";
import { Orientation } from "@gtkx/ffi/gtk";
import { useState } from "react";

const App = () => {
  const [count, setCount] = useState(0);

  return (
    <ApplicationWindow title="Counter" onCloseRequest={quit}>
      <Box orientation={Orientation.VERTICAL} spacing={12}>
        <Label.Root label={`Count: ${count}`} />
        <Button label="Increment" onClicked={() => setCount((c) => c + 1)} />
      </Box>
    </ApplicationWindow>
  );
};

render(<App />, "org.example.Counter");

Styling

import { css } from "@gtkx/css";
import { Button } from "@gtkx/react";

const primary = css`
  padding: 16px 32px;
  border-radius: 24px;
  background: linear-gradient(135deg, #3584e4, #9141ac);
  color: white;
`;

<Button label="Click me" cssClasses={[primary]} />;

GTK also provides built-in classes like suggested-action, destructive-action, card, and heading.

Testing

import { cleanup, render, screen, userEvent } from "@gtkx/testing";
import { AccessibleRole } from "@gtkx/ffi/gtk";

afterEach(() => cleanup());

test("increments count", async () => {
  await render(<App />);

  const button = await screen.findByRole(AccessibleRole.BUTTON, {
    name: "Increment",
  });
  await userEvent.click(button);

  await screen.findByText("Count: 1");
});

Queries: findByRole, findByText, findByLabelText, findByTestId

User events: click, dblClick, type, clear, tab, selectOptions

Examples

| Example | Description | | ------------------------------- | ------------------- | | gtk4-demo | Widget showcase | | todo | Todo app with tests |

Packages

| Package | Description | | --------------------------------- | ------------------------------------- | | @gtkx/cli | CLI with HMR dev server | | @gtkx/react | React reconciler and JSX components | | @gtkx/ffi | TypeScript bindings for GTK4/GLib/GIO | | @gtkx/native | Rust native module (libffi bridge) | | @gtkx/css | CSS-in-JS styling | | @gtkx/testing | Testing utilities | | @gtkx/gir | GObject Introspection parser |

Requirements

• Node.js 20+
• GTK4 Runtime (gtk4 on Fedora, libgtk-4-1 on Ubuntu)
• Linux

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

• Report a bug
• Request a feature

License

MPL-2.0