Skip to main content

Getting Started

This guide will help you set up GTKX and create your first GTK4 application with React.

Prerequisites​

Before you begin, make sure you have:

  • Node.js 20+ — GTKX uses modern JavaScript features
  • npm, yarn, or pnpm — For package management
  • GTK4 development libraries — Required for native bindings
  • Linux — GTK4 is designed for Linux (GNOME desktop)

Installing GTK4​

On Fedora:

sudo dnf install gtk4-devel

On Ubuntu/Debian:

sudo apt install libgtk-4-dev

On Arch Linux:

sudo pacman -S gtk4

Installation​

Create a new project and install GTKX:

mkdir my-gtk-app
cd my-gtk-app
npm init -y
npm install @gtkx/react @gtkx/ffi react

For TypeScript (recommended):

npm install -D @types/react tsx typescript

For styling support:

npm install @gtkx/css

For testing support:

npm install -D @gtkx/testing

Project Setup​

Create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Update your package.json:

{
  "type": "module",
  "scripts": {
    "start": "tsx src/index.tsx"
  }
}

Your First App​

Create the following files in a src directory:

src/index.tsx​

import { render } from "@gtkx/react";
import { App } from "./app.js";

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

The render function initializes GTK and mounts your React tree. The second argument is your application ID (reverse domain notation).

src/app.tsx​

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

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

  return (
    <ApplicationWindow
      title="My First GTKX App"
      defaultWidth={400}
      defaultHeight={300}
      onCloseRequest={quit}
    >
      <Box
        orientation={Orientation.VERTICAL}
        spacing={12}
        marginTop={20}
        marginBottom={20}
        marginStart={20}
        marginEnd={20}
      >
        <Label.Root label={`You clicked ${count} times`} />
        <Box orientation={Orientation.HORIZONTAL} spacing={8}>
          <Button
            label="Decrement"
            onClicked={() => setCount(c => c - 1)}
          />
          <Button
            label="Increment"
            onClicked={() => setCount(c => c + 1)}
          />
        </Box>
      </Box>
    </ApplicationWindow>
  );
};

Running Your App​

Start your application:

npm start

You should see a native GTK4 window with your counter application!

Understanding the Code​

render(element, appId)​

The entry point for GTKX applications. It:

  1. Initializes the GTK main loop
  2. Creates a GTK Application with the given ID
  3. Mounts your React element tree
  4. Starts the event loop

ApplicationWindow​

The main window component. Key props:

  • title — Window title
  • defaultWidth / defaultHeight — Initial window size
  • onCloseRequest — Called when the window close button is clicked

quit()​

Cleanly shuts down the application by:

  1. Unmounting the React tree
  2. Stopping the GTK main loop

Always use quit() in onCloseRequest to ensure proper cleanup.

Layout with Box​

Box is the primary layout container in GTK. Use orientation to set horizontal or vertical layout, and spacing to add gaps between children.

Handling Events​

GTK signals are exposed as React props with the on prefix:

  • onClicked — Button clicks
  • onCloseRequest — Window close
  • onChanged — Text input changes

Next Steps​