Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/devhammed/react-gtk/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through creating a basic GTK application using React GTK. You’ll learn how to set up a simple window with UI components and handle user interactions.

​
Overview

A basic React GTK application consists of:
  • A GtkWindow as the top-level container
  • Layout components like GtkBox to organize widgets
  • UI widgets like GtkLabel and GtkButton
  • React state management for interactivity
1

Set up the application entry point

Create your main entry file that initializes the GTK application:
index.tsx
import { MyApp } from './components/app';
import { createRoot } from 'react-gtk-renderer';

declare const imports: any;

imports.package.init({
  name: '@PACKAGE_ID@',
  version: '@PACKAGE_VERSION@',
  prefix: '@PREFIX@',
  libdir: '@LIBDIR@',
  pkgdatadir: '@PKGDATADIR@',
});

imports.package.run({
  main: function (argv: string[]) {
    const root = createRoot({
      id: '@PACKAGE_ID@',
    });

    root.render(<MyApp />, argv);
  },
});
The createRoot function initializes the React GTK renderer, similar to React DOM’s createRoot.
2

Create a basic window component

Build your main application component with a window, label, and button:
app.tsx
import {
  GtkAlign,
  GtkBox,
  GtkButton,
  GtkLabel,
  GtkOrientation,
  GtkWindow,
} from 'react-gtk-renderer';
import { useState } from 'react';

export function MyApp() {
  const [count, setCount] = useState(0);

  return (
    <GtkWindow defaultHeight={600} defaultWidth={800} title='My App'>
      <GtkBox
        marginStart={25}
        marginEnd={25}
        spacing={25}
        valign={GtkAlign.CENTER}
        halign={GtkAlign.CENTER}
        orientation={GtkOrientation.VERTICAL}>
        <GtkLabel label='Hello World' />

        <GtkButton onClicked={() => setCount((prev) => prev + 1)}>
          {`You have clicked me ${count} times`}
        </GtkButton>
      </GtkBox>
    </GtkWindow>
  );
}
3

Understand the component structure

GtkWindow: The top-level window container
  • defaultHeight and defaultWidth: Set the initial window size
  • title: The window title displayed in the title bar
GtkBox: A container that arranges children in a single row or column
  • orientation: Use GtkOrientation.VERTICAL or GtkOrientation.HORIZONTAL
  • spacing: Space between child widgets
  • marginStart and marginEnd: Padding around the box
  • valign and halign: Vertical and horizontal alignment
GtkLabel: Displays text
  • label: The text content to display
GtkButton: An interactive button
  • onClicked: Event handler when the button is clicked
  • Children: The button label (can be text or other components)

​
Adding Conditional Rendering

You can use React’s conditional rendering with GTK components: 
import { useMemo } from 'react';

export function MyApp() {
  const [count, setCount] = useState(0);
  const hasClickedSixTimes = useMemo(() => count === 6, [count]);

  return (
    <GtkWindow defaultHeight={600} defaultWidth={800} title='My App'>
      <GtkBox
        marginStart={25}
        marginEnd={25}
        spacing={25}
        valign={GtkAlign.CENTER}
        halign={GtkAlign.CENTER}
        orientation={GtkOrientation.VERTICAL}>
        <GtkLabel label='Hello World' />

        {hasClickedSixTimes && (
          '<i>Hi World, testing insertBefore and text instance!</i>'
        )}

        <GtkButton onClicked={() => setCount((prev) => prev + 1)}>
          {hasClickedSixTimes
            ? `You are now a developer, click again!`
            : `You have clicked me ${count} times`}
        </GtkButton>
      </GtkBox>
    </GtkWindow>
  );
}
React GTK supports standard React features like hooks, conditional rendering, and state management. You can use useState, useEffect, useMemo, and other React hooks just like in React DOM applications.

​
Key Concepts

GTK uses a box model for layout. The GtkBox component is fundamental for arranging widgets:
  • Vertical orientation: Stacks children from top to bottom
  • Horizontal orientation: Arranges children from left to right
  • Alignment: Control positioning with valign (top, center, bottom) and halign (start, center, end)
  • Spacing: Add gaps between children with the spacing property
GTK widgets emit signals that you can handle with React props:
  • GtkButton uses onClicked for click events
  • Event handlers receive the widget instance as an argument
  • You can update React state in event handlers to trigger re-renders
The GtkWindow component accepts several properties:
  • title: Window title text
  • defaultWidth and defaultHeight: Initial window dimensions
  • modal: Make the window modal (blocks interaction with other windows)
  • resizable: Whether the window can be resized (default: true)

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us