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.

Learn how to create and manage multiple windows in your React GTK application, including modal dialogs and window lifecycle management.

​
Overview

React GTK allows you to render multiple GtkWindow components simultaneously. This is useful for:
  • Creating dialog windows
  • Building multi-window applications
  • Showing modal popups
  • Managing secondary application windows

​
Creating Multiple Windows

You can render multiple GtkWindow components by returning them as siblings in a React fragment: 
import { GtkWindow, GtkBox, GtkButton, GtkLabel } from 'react-gtk-renderer';
import { useRef } from 'react';

export function MyApp() {
  const secondWinRef = useRef<GtkWindowImpl>();

  return (
    <>
      <GtkWindow defaultHeight={600} defaultWidth={800} title='Main Window'>
        {/* Main window content */}
      </GtkWindow>

      <GtkWindow
        modal
        ref={secondWinRef}
        defaultHeight={500}
        defaultWidth={500}
        title='Secondary Window'>
        {/* Secondary window content */}
      </GtkWindow>
    </>
  );
}
Use React fragments (<>...</>) to return multiple windows from your component without adding extra DOM nodes.

​
Complete Example: Modal Dialog

Here’s a full example showing how to create a main window with a button that opens a modal dialog:
1

Set up component state and refs

import {
  GtkAlign,
  GtkBox,
  GtkButton,
  GtkLabel,
  GtkOrientation,
  GtkWindow,
  GtkWindowImpl,
} from 'react-gtk-renderer';
import { useRef, useState } from 'react';

export function MyApp() {
  const [count, setCount] = useState(0);
  const secondWinRef = useRef<GtkWindowImpl>();
  const hasClickedSixTimes = count === 6;

  // Component continues...
}
2

Create the main window

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={
            hasClickedSixTimes
              ? () => {
                  secondWinRef.current?.present();
                  setCount(0);
                }
              : () => setCount((prev) => prev + 1)
          }>
          {hasClickedSixTimes
            ? `You are now a developer, click again!`
            : `You have clicked me ${count} times`}
        </GtkButton>
      </GtkBox>
    </GtkWindow>

    {/* Second window defined below */}
  </>
);
3

Add the modal window

<GtkWindow
  modal
  ref={secondWinRef}
  defaultHeight={500}
  defaultWidth={500}
  title='Royal Hotness'>
  <GtkBox
    marginStart={25}
    marginEnd={25}
    spacing={25}
    valign={GtkAlign.CENTER}
    halign={GtkAlign.CENTER}
    orientation={GtkOrientation.VERTICAL}>
    <GtkLabel label='I am here to tell you that your head is hot.' />

    <GtkButton onClicked={() => secondWinRef.current?.close()}>
      Close Me
    </GtkButton>
  </GtkBox>
</GtkWindow>

​
Window Control Methods

Use refs to control window behavior programmatically: 
// Show and raise the window to the front
secondWinRef.current?.present();

​
Window Properties

Control window dimensions with:
  • defaultWidth and defaultHeight: Initial window size
  • resizable: Whether users can resize the window (default: true)
<GtkWindow
  defaultWidth={400}
  defaultHeight={300}
  resizable={false}>
  {/* Fixed-size window */}
</GtkWindow>
Use React refs to access window instances:
import { useRef } from 'react';
import { GtkWindowImpl } from 'react-gtk-renderer';

const windowRef = useRef<GtkWindowImpl>();

// Access methods
windowRef.current?.present();
windowRef.current?.close();
The ref provides access to GTK window methods for programmatic control.

​
Best Practices

Window Lifecycle: By default, secondary windows may not be visible when first rendered. Use the present() method to show them when needed, typically in response to user actions.
Memory Management: Windows persist until explicitly closed. Make sure to provide users with a way to close secondary windows, either through a close button or the window’s close control.

​
Common Patterns

​
Conditional Window Rendering

You can conditionally render windows based on state: 
const [showDialog, setShowDialog] = useState(false);

return (
  <>
    <GtkWindow title='Main'>
      <GtkButton onClicked={() => setShowDialog(true)}>
        Open Dialog
      </GtkButton>
    </GtkWindow>

    {showDialog && (
      <GtkWindow modal title='Dialog'>
        <GtkButton onClicked={() => setShowDialog(false)}>
          Close
        </GtkButton>
      </GtkWindow>
    )}
  </>
);

​
Window Communication

Use shared state to communicate between windows: 
const [message, setMessage] = useState('');

return (
  <>
    <GtkWindow title='Window 1'>
      <GtkLabel label={message} />
    </GtkWindow>

    <GtkWindow title='Window 2'>
      <GtkButton onClicked={() => setMessage('Hello from Window 2!')}>
        Send Message
      </GtkButton>
    </GtkWindow>
  </>
);

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us