Skip to main content

​
Overview

The createRoot function creates a root application instance that enables you to render React components into a GTK+ desktop application. It initializes a GTK Application with the specified configuration and returns a RootAppInstance that can be used to render your React component tree.

​
Signature

function createRoot(config: RootAppConfig): RootAppInstance

​
Parameters

​
config
RootAppConfig
required
Configuration object for the root application
​
config.id
string
required
The application ID (typically in reverse DNS notation, e.g., com.example.myapp)
​
config.flags
number
default:"Gio.ApplicationFlags.FLAGS_NONE"
GTK application flags. Common values include:
  • Gio.ApplicationFlags.FLAGS_NONE - No special flags
  • Gio.ApplicationFlags.HANDLES_OPEN - Application can open files
  • Gio.ApplicationFlags.HANDLES_COMMAND_LINE - Application handles command line

​
Return Value

​
RootAppInstance
object
An instance of the root application with the following method:
​
render
function
Renders the React component tree into the GTK application.Signature:
render(element: JSX.Element, argv?: string[]): void
Parameters:
  • element (JSX.Element) - The root React component to render
  • argv (string[], optional) - Command-line arguments array (defaults to [])

​
Usage

​
Basic Example

import { createRoot } from 'react-gtk-renderer';
import { MyApp } from './components/app';

// Create the root instance
const root = createRoot({
  id: 'com.example.myapp',
});

// Render your React component
root.render(<MyApp />);

​
With Command-Line Arguments

import { createRoot } from 'react-gtk-renderer';
import { MyApp } from './components/app';

const root = createRoot({
  id: 'com.example.myapp',
});

// Pass command-line arguments to the GTK application
root.render(<MyApp />, process.argv);

​
With Application Flags

import { createRoot } from 'react-gtk-renderer';
import { MyApp } from './components/app';

declare const imports: any;
const { Gio } = imports.gi;

const root = createRoot({
  id: 'com.example.myapp',
  flags: Gio.ApplicationFlags.HANDLES_OPEN,
});

root.render(<MyApp />);

​
Complete Application Setup

import { createRoot } from 'react-gtk-renderer';
import { GtkWindow, GtkButton } from 'react-gtk-renderer';

declare const imports: any;

imports.package.init({
  name: 'com.example.myapp',
  version: '1.0.0',
  prefix: '/usr',
  libdir: '/usr/lib',
  pkgdatadir: '/usr/share/myapp',
});

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

    root.render(
      <GtkWindow title="My Application" defaultWidth={400} defaultHeight={300}>
        <GtkButton label="Click Me" />
      </GtkWindow>,
      argv
    );
  },
});

​
Type Definitions

​
RootAppConfig

interface RootAppConfig {
  id: string;
  flags?: number;
}

​
RootAppInstance

interface RootAppInstance {
  render(element: JSX.Element, argv: string[]): void;
}

​
Notes

The createRoot function must be called before rendering any React components. It sets up the underlying GTK Application and React reconciler.
The application ID should follow reverse DNS notation (e.g., com.example.myapp) to ensure uniqueness across the system.
The render method blocks until the GTK application exits, so it should typically be the last call in your main function.