GtkWidget

GtkWidget is the abstract base class for all UI components in React GTK. While you typically don’t use GtkWidget directly, all other components inherit its props and behaviors.

Common Props

These props are available on all widgets:

Layout

widthRequest

number

Override for width request of the widget in pixels.

heightRequest

number

Override for height request of the widget in pixels.

halign

GtkAlign

How to distribute horizontal space if widget gets extra space.Options: GtkAlign.FILL, GtkAlign.START, GtkAlign.END, GtkAlign.CENTER

valign

GtkAlign

How to distribute vertical space if widget gets extra space.Options: GtkAlign.FILL, GtkAlign.START, GtkAlign.END, GtkAlign.CENTER

hexpand

boolean

Whether to expand horizontally to fill available space.Default: false

vexpand

boolean

Whether to expand vertically to fill available space.Default: false

hexpandSet

boolean

Whether to use the hexpand property.Default: false

vexpandSet

boolean

Whether to use the vexpand property.Default: false

Margins

marginStart

number

Margin on the start edge (left in LTR, right in RTL) in pixels.

marginEnd

number

Margin on the end edge (right in LTR, left in RTL) in pixels.

marginTop

number

Margin on the top edge in pixels.

marginBottom

number

Margin on the bottom edge in pixels.

Visibility & Interaction

visible

boolean

Whether the widget is visible.Default: true

sensitive

boolean

Whether the widget responds to input.Default: true

canFocus

boolean

Whether the widget or any of its descendants can accept input focus.Default: Varies by widget type

canTarget

boolean

Whether the widget can receive pointer events.Default: true

focusable

boolean

Whether this widget itself will accept input focus.Default: Varies by widget type

focusOnClick

boolean

Whether the widget should grab focus when clicked with the mouse.Default: Varies by widget type

hasFocus

boolean

Whether the widget has input focus.

hasDefault

boolean

Whether the widget is the default widget.

receivesDefault

boolean

Whether the widget will receive the default action when focused.Default: false

Styling

cssClasses

string[]

A list of CSS classes applied to this widget.

opacity

number

The requested opacity of the widget (0.0 to 1.0).Default: 1.0

cursor

string

The cursor to display when hovering over the widget.Options: 'none', 'default', 'pointer', 'text', 'wait', 'crosshair', 'help', 'move', 'not-allowed', and many more.

overflow

GtkOverflow

How content outside the widget’s content area is treated.Options: GtkOverflow.VISIBLE, GtkOverflow.HIDDEN

Tooltips

Enables or disables the tooltip for this widget.Default: false

Sets the text of the tooltip as plain text.

Sets the text of the tooltip with Pango markup.

Other

name

string

The name of the widget. Used for identification and CSS styling.

accessibleRole

GtkAccessibleRole

The accessible role of the widget. Cannot be changed once set.

layoutManager

any

The layout manager to compute preferred size and allocate children.

Events

Lifecycle Events

onRealize

(self: GtkWidgetImpl) => void

Emitted when the widget is associated with a GdkSurface (about to be drawn).

onUnrealize

(self: GtkWidgetImpl) => void

Emitted when the GdkSurface associated with the widget is destroyed.

onMap

(self: GtkWidgetImpl) => void

Emitted when the widget is going to be mapped (visible with visible parents).

onUnmap

(self: GtkWidgetImpl) => void

Emitted when the widget is going to be unmapped (hidden).

onShow

(self: GtkWidgetImpl) => void

Emitted when the widget is shown.

onHide

(self: GtkWidgetImpl) => void

Emitted when the widget is hidden.

onDestroy

(self: GtkWidgetImpl) => void

Emitted when all holders should release their references to the widget.

onMoveFocus

(self: GtkWidgetImpl, direction: GtkDirectionType) => void

Emitted when focus is moved.

onKeynavFailed

(self: GtkWidgetImpl, direction: GtkDirectionType) => boolean

Emitted if keyboard navigation fails. Return true to stop navigation, false to propagate.

onMnemonicActivate

(self: GtkWidgetImpl, groupCycling: boolean) => boolean

Emitted when a widget is activated via a mnemonic. Return true to stop propagation.

State Changes

onNotify

(self: GtkWidgetImpl, paramSpec: any) => void

Emitted when a property value changes.

onStateFlagsChanged

(self: GtkWidgetImpl, flags: GtkStateFlags) => void

Emitted when the widget state changes.

onDirectionChanged

(self: GtkWidgetImpl, previousDirection: GtkTextDirection) => void

Emitted when the text direction changes.

Tooltips

Emitted when the widget’s tooltip is about to be shown. Return true to show tooltip, false otherwise.

Instance Properties

When using a ref on any widget, you can access these properties:

visible

Get or set widget visibility:

const widgetRef = useRef<GtkWidgetImpl>();

// Get visibility
const isVisible = widgetRef.current.visible;

// Set visibility
widgetRef.current.visible = false;

name

Get or set widget name:

const widgetRef = useRef<GtkWidgetImpl>();

// Get name
const widgetName = widgetRef.current.name;

// Set name
widgetRef.current.name = "my-widget";

parent

Get the widget’s parent:

const parent = widgetRef.current.parent;

root

Get the root widget of the widget tree:

const root = widgetRef.current.root;

scaleFactor

Get the scale factor of the widget (for HiDPI displays):

const scale = widgetRef.current.scaleFactor;

Instance Methods

realize()

Creates the GDK resources associated with the widget:

widgetRef.current.realize();

unrealize()

Frees all GDK resources associated with the widget:

widgetRef.current.unrealize();

unparent()

Dissociates the widget from its parent:

widgetRef.current.unparent();

detach()

Destroys the widget instance by unparenting and unrealizing:

widgetRef.current.detach();

Usage Examples

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

function CenteredButton() {
  return (
    <GtkButton
      label="I'm Centered"
      halign={GtkAlign.CENTER}
      valign={GtkAlign.CENTER}
    />
  );
}

import { GtkLabel } from 'react-gtk-renderer';

function SpacedLabel() {
  return (
    <GtkLabel
      label="Spaced Out"
      marginStart={20}
      marginEnd={20}
      marginTop={10}
      marginBottom={10}
    />
  );
}

import { GtkButton } from 'react-gtk-renderer';

function ButtonWithTooltip() {
  return (
    <GtkButton
      label="Hover Me"
      hasTooltip
      tooltipText="This is a helpful tooltip"
    />
  );
}

Custom Cursor

import { GtkButton } from 'react-gtk-renderer';

function PointerButton() {
  return (
    <GtkButton
      label="Click Me"
      cursor="pointer"
    />
  );
}

import { GtkButton } from 'react-gtk-renderer';

function FixedButton() {
  return (
    <GtkButton
      label="Fixed Size"
      widthRequest={200}
      heightRequest={50}
    />
  );
}

import { GtkLabel } from 'react-gtk-renderer';

function StyledLabel() {
  return (
    <GtkLabel
      label="Styled Text"
      cssClasses={['title', 'primary']}
    />
  );
}

Conditional Visibility

import { GtkLabel } from 'react-gtk-renderer';
import { useState } from 'react';

function ToggleableLabel() {
  const [isVisible, setIsVisible] = useState(true);
  
  return (
    <>
      <GtkLabel label="I can disappear!" visible={isVisible} />
      <GtkButton 
        label={isVisible ? "Hide" : "Show"}
        onClicked={() => setIsVisible(!isVisible)}
      />
    </>
  );
}

Notes

All other components in React GTK inherit these props. You can use any GtkWidget prop on components like GtkButton, GtkLabel, GtkBox, etc.

The visible prop controls visibility, but hidden widgets still take up layout space unless completely removed from the tree.

Setting sensitive={false} disables all user interaction with the widget and its children. The widget will appear grayed out.

Core API

Components

Types & Enums

Common Props

Layout

Margins

Visibility & Interaction

Styling

Tooltips

Other

Events

Lifecycle Events

Focus & Navigation

State Changes

Tooltips

Instance Properties

visible

name

parent

root

scaleFactor

Instance Methods

realize()

unrealize()

unparent()

detach()

Usage Examples

Centered Widget

Widget with Margins

Widget with Tooltip

Custom Cursor

Fixed Size Widget

Widget with CSS Classes

Conditional Visibility

Notes

Build docs developers (and LLMs) love

Core API

Components

Types & Enums

Documentation Index

​Common Props

​Layout

​Margins

​Visibility & Interaction

​Styling

​Tooltips

​Other

​Events

​Lifecycle Events

​Focus & Navigation

​State Changes

​Tooltips

​Instance Properties

​visible

​name

​parent

​root

​scaleFactor

​Instance Methods

​realize()

​unrealize()

​unparent()

​detach()

​Usage Examples

​Centered Widget

​Widget with Margins

​Widget with Tooltip

​Custom Cursor

​Fixed Size Widget

​Widget with CSS Classes

​Conditional Visibility

​Notes

Build docs developers (and LLMs) love

Common Props

Layout

Margins

Visibility & Interaction

Styling

Tooltips

Other

Events

Lifecycle Events

Focus & Navigation

State Changes

Tooltips

Instance Properties

visible

name

parent

root

scaleFactor

Instance Methods

realize()

unrealize()

unparent()

detach()

Usage Examples

Centered Widget

Widget with Margins

Widget with Tooltip

Custom Cursor

Fixed Size Widget

Widget with CSS Classes

Conditional Visibility

Notes