UIng

UIng is a Crystal binding for kojix2/libui-ng. You can use the Crystal language to create cross-platform native desktop apps.

Documentation: Guide · English · 日本語 · API Reference

libui-ng uses the native APIs of each platform: Win32 API, Direct2D, and DirectWrite on Windows; Cocoa (AppKit) on macOS; and GTK+ 3.10+ and Pango on Linux/Unix. You get windows, buttons, text boxes, menus, dialogs, drawing areas, and other standard widgets.

Windows	Mac	Linux

📸 Live Documentation: All screenshots in the README are automatically generated by GitHub Actions on every push, ensuring cross-platform compatibility (Linux, Windows, macOS).

Supported Platforms

macOS: x86_64 (64-bit), ARM64 (Apple Silicon)
Linux: x86_64 (64-bit), ARM64
Windows: x86_64 (64-bit, MSVC and MSYS2 UCRT64)

MinGW64 is no longer supported; use the MSYS2 UCRT64 environment for GNU-style builds.

Installation

Add the dependency to your shard.yml:

dependencies:
  uing:
    github: kojix2/uing

Run shards install. The post-install script downloads the required libui-ng binary for the current platform. See the installation guide for platform-specific setup.

Quick Start

Create hello.cr:

require "uing"

UIng.init

window = UIng::Window.new("Hello World", 300, 200)
window.on_closing do
  UIng.quit
  true
end

button = UIng::Button.new("Click me")
button.on_clicked do
  window.msg_box("Info", "Button clicked!")
end

window.child = button
window.show

UIng.main
UIng.uninit

Run it with:

crystal run hello.cr

To run the full control gallery from a checkout:

git clone https://github.com/kojix2/uing
cd uing
shards install
crystal run examples/crimage/control_gallery.cr

Continue with the First Steps guide. The optional block-based DSL is covered in Coding Styles.

Examples Gallery

This gallery shows screenshots of example on three platforms (Ubuntu, Windows, macOS).
Images are automatically generated and stored in the screenshots branch.

Window

Control	Ubuntu	Windows	macOS
Window
Toolbar

Note: Toolbar is a feature specific to kojix2/libui-ng. It is experimental and may change.

If you're looking for icons under the MIT license, try icon-viewer.

Control

Control	Ubuntu	Windows	macOS
Button
Checkbox
ColorButton
Combobox
DateTimePicker
EditableCombobox
Entry
FontButton
Label
MultilineEntry
Progressbar
RadioButtons
Separator
Slider
Spinbox

Container Control

Container	Ubuntu	Windows	macOS
Box (Horizontal)
Box (Vertical)
Tab
Form
Group
Grid
Grid (Calculator)

Table

Example	Ubuntu	Windows	macOS
basic_table
csv_viewer
advanced_table

Area

Example	Ubuntu	Windows	macOS
basic_area
area_events
area_basic_shapes
area_colors_and_brushes
area_analog_clock
area_matrix
basic_draw_text
reversi
area_breakout
boid3d

Example	Ubuntu	Windows	macOS
basic_menu

Dialog

Example	Ubuntu	Windows	macOS
basic_msg_box
basic_msg_box_error

Image

require "uing/crimage" enables optional helpers for reading images, converting CrImage pixels, and passing CrImage colors to UIng controls. Applications using these helpers must declare crimage in their own shard.yml. Plain require "uing" does not load it. CrImage examples are kept in examples/crimage/. See the ImageView guide for usage and image ownership rules.