GtkWidget

The base class for all widgets, providing common properties and behaviors

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

hasTooltip · boolean

Enables or disables the tooltip for this widget.

Default: false

tooltipText · string

Sets the text of the tooltip as plain text.

tooltipMarkup · string

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.

Focus & Navigation

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

onQueryTooltip · (self: GtkWidgetImpl, x: number, y: number, isKeyboardMode: boolean, tooltip: GtkTooltip) => boolean

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

Centered Widget

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

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

Widget with Margins

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

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

Widget with Tooltip

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"
    />
  );
}

Fixed Size Widget

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

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

Widget with CSS Classes

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.