Introduction

Requirements

Zaniah runs on CRuby 3.1 or newer. Add the gem to your Gemfile and install it with Bundler. The component library is opt-in: load zaniah/ui when you need controls.

gem "zaniah"

Your first image

Use the headless backend to render a frame without opening a desktop window. Save the result as a PNG, which is also useful for visual tests.

require "zaniah"

window = Zaniah::Platform.open_window(
  backend: :headless, width: 480, height: 240
)
window.text_system = Zaniah::TextSystem::Renderer.new
window.draw do
  Zaniah::Div.new.flex_col.p(24).gap(12).bg("#161b22")
    .child(Zaniah::Text.new("Hello, Ruby", size: 24))
    .child(Zaniah::Text.new("A native toolkit, written in Ruby."))
end
window.tick
window.write_png("hello.png")
window.close

Run bundle exec ruby hello.rb to create hello.png in the current directory.

Open a window

Switch to a native backend and call run instead of rendering a single frame. Load zaniah/ui to use the component library.

require "zaniah/ui"

window = Zaniah::Platform.open_window(
  backend: :mac, width: 640, height: 360
)
window.draw do
  Zaniah::Div.new.flex_col.p(24).gap(12)
    .child(Zaniah::UI::Label.new("Hello, Zaniah", size: :xl))
    .child(Zaniah::UI::Button.new("Save", variant: :primary)
      .on_click { puts "Saved" })
end
window.run

Use :linux, :windows, or :tui for other interactive backends. See the Native backends guide for platform requirements.

Next steps

Open Guides for platform and API topics, or Components overview to find the right control. Each component page shows a rendered example, Ruby code, constructor options, and accessibility roles.