component-api

name	component-api
description	Full API reference for all UI::View types, value types, enums, and composition patterns
version	2.0

Component API Reference

Complete API reference for the cross-platform UI::View hierarchy defined in src/ui/.

---

Value Types

UI::Color

RGBA color with floating-point components in the range 0.0 to 1.0.

record Color,
  r : Float64,
  g : Float64,
  b : Float64,
  a : Float64 = 1.0

Usage:

red   = UI::Color.new(r: 1.0, g: 0.0, b: 0.0)
white = UI::Color.new(r: 1.0, g: 1.0, b: 1.0)
semi  = UI::Color.new(r: 0.0, g: 0.0, b: 0.0, a: 0.5)

UI::Font

Font specification with family, size, weight, and italic flag.

record Font,
  family : String = "system",
  size : Float64 = 17.0,
  weight : Symbol = :regular,
  italic : Bool = false

Weight values: :ultralight, :thin, :light, :regular, :medium, :semibold, :bold, :heavy, :black

Usage:

heading = UI::Font.new(size: 24.0, weight: :bold)
mono    = UI::Font.new(family: "monospace", size: 14.0)
italic  = UI::Font.new(weight: :medium, italic: true)
default = UI::Font.new  # system font, 17pt, regular

UI::EdgeInsets

Edge insets for padding or margin values, in points.

record EdgeInsets,
  top : Float64 = 0.0,
  trailing : Float64 = 0.0,
  bottom : Float64 = 0.0,
  leading : Float64 = 0.0

Note: Uses leading/trailing (not left/right) for RTL language support.

Usage:

uniform  = UI::EdgeInsets.new(top: 16.0, trailing: 16.0, bottom: 16.0, leading: 16.0)
vertical = UI::EdgeInsets.new(top: 8.0, bottom: 8.0)
none     = UI::EdgeInsets.new  # all zeros

UI::ThemeColor

Semantic color in UI::Theme. Same RGBA structure as UI::Color but semantically scoped to theme roles.

record ThemeColor,
  r : Float64,
  g : Float64,
  b : Float64,
  a : Float64 = 1.0

---

Enums

UI::Alignment

Controls alignment of children within stack layouts.

enum Alignment
  Leading   # Left-aligned (or start, in RTL)
  Center    # Center-aligned
  Trailing  # Right-aligned (or end, in RTL)
  Top       # Top-aligned (for HStack vertical alignment)
  Bottom    # Bottom-aligned (for HStack vertical alignment)
  Fill      # Stretch to fill available space
end

• VStack uses Leading, Center, Trailing, Fill for horizontal alignment of children
• HStack uses Top, Center, Bottom, Fill for vertical alignment of children
• ZStack uses Leading, Center, Trailing, Top, Bottom for overlay positioning

UI::ContentMode

Controls how an image is scaled to fit its bounds.

enum ContentMode
  Fit      # Scale to fit within bounds, preserving aspect ratio (may letterbox)
  Fill     # Scale to fill bounds, preserving aspect ratio (may crop)
  Stretch  # Scale to exactly fill bounds (may distort)
end

UI::KeyboardType

Hint for the platform's virtual keyboard type on mobile.

enum KeyboardType
  Default       # Standard text keyboard
  EmailAddress  # Keyboard optimized for email input (@ key prominent)
  NumberPad     # Numeric-only keyboard
  PhonePad      # Phone number keyboard
  URL           # Keyboard optimized for URL input
end

UI::ToggleStyle

Visual style for UI::Toggle.

enum ToggleStyle
  Switch    # iOS-style toggle switch (thumb that slides)
  Checkbox  # Standard checkbox
end

UI::PickerStyle

Visual style for UI::Picker.

enum PickerStyle
  Wheel     # Spinning wheel picker (iOS UIPickerView style)
  Segmented # Segmented control inline
  Menu      # Dropdown/popup menu (default)
  Inline    # Expanded inline
end

UI::DatePickerMode

What components the date picker shows.

enum DatePickerMode
  Date         # Date only
  Time         # Time only
  DateAndTime  # Both date and time
end

UI::ProgressStyle

Visual style for UI::ProgressView.

enum ProgressStyle
  Linear    # Horizontal progress bar
  Circular  # Spinning circular progress
end

UI::ListStyle

Visual style for UI::ListView.

enum ListStyle
  Plain         # No grouping, no separators between sections
  Inset         # Rounded group sections with insets
  Grouped       # Grouped with section headers
  InsetGrouped  # Rounded grouped sections
  Sidebar       # macOS-style sidebar list
end

---

Abstract Base: UI::View

File: src/ui/view.cr

All concrete view types inherit from this abstract class.

abstract class UI::View
  # Identity & accessibility
  property id : String? = nil
  property accessibility_label : String? = nil

  # Layout
  property padding : EdgeInsets = EdgeInsets.new
  property background : Color? = nil
  property hidden : Bool = false
  property opacity : Float64 = 1.0

  # Shape modifiers
  property corner_radius : Float64 = 0.0
  property clip_to_bounds : Bool = false

  # Shadow modifier
  property shadow_radius : Float64 = 0.0
  property shadow_color : Color? = nil
  property shadow_offset_x : Float64 = 0.0
  property shadow_offset_y : Float64 = 0.0

  # Border modifier
  property border_width : Float64 = 0.0
  property border_color : Color? = nil

  # Blur modifier
  property blur_radius : Float64 = 0.0

  # Size constraints
  property minimum_width : Float64? = nil
  property minimum_height : Float64? = nil
  property maximum_width : Float64? = nil
  property maximum_height : Float64? = nil

  abstract def accept(visitor : PlatformVisitor)
end

Property	Type	Default	Description
id	String?	nil	Optional identifier for lookup and testing
accessibility_label	String?	nil	Screen reader label
padding	EdgeInsets	all zeros	Content padding
background	Color?	nil	Background color (nil = transparent/inherited)
hidden	Bool	false	Whether the view is hidden from display
opacity	Float64	1.0	Opacity from 0.0 (transparent) to 1.0 (opaque)
corner_radius	Float64	0.0	Corner radius in points
clip_to_bounds	Bool	false	Clip children to bounds
shadow_radius	Float64	0.0	Shadow blur radius (0 = no shadow)
shadow_color	Color?	nil	Shadow color
shadow_offset_x	Float64	0.0	Shadow horizontal offset
shadow_offset_y	Float64	0.0	Shadow vertical offset
border_width	Float64	0.0	Border stroke width (0 = no border)
border_color	Color?	nil	Border stroke color
blur_radius	Float64	0.0	Blur radius (0 = no blur)
minimum_width	Float64?	nil	Minimum width constraint
minimum_height	Float64?	nil	Minimum height constraint
maximum_width	Float64?	nil	Maximum width constraint
maximum_height	Float64?	nil	Maximum height constraint

---

Concrete View Types

P0 Base Views

---

UI::Label

File: src/ui/views/label.cr

Read-only text display.

class UI::Label < UI::View
  property text : String
  property font : Font = Font.new
  property text_color : Color = Color.new(r: 0.0, g: 0.0, b: 0.0)
  property text_alignment : Alignment = Alignment::Leading
  property number_of_lines : Int32 = 0

  def initialize(@text : String)
end

Property	Type	Default	Description
text	String	(required)	The displayed text content
font	Font	system 17pt	Font specification
text_color	Color	black	Text foreground color
text_alignment	Alignment	Leading	Horizontal text alignment
number_of_lines	Int32	0	Max lines to display (0 = unlimited)

Example:

title = UI::Label.new("Welcome Back")
title.font = UI::Font.new(size: 28.0, weight: :bold)
title.text_color = UI::Color.new(r: 0.2, g: 0.2, b: 0.2)
title.text_alignment = UI::Alignment::Center

---

UI::Button

File: src/ui/views/button.cr

A tappable button with a text label.

class UI::Button < UI::View
  property label : String
  property font : Font = Font.new
  property foreground_color : Color = Color.new(r: 0.0, g: 0.478, b: 1.0)
  property disabled : Bool = false
  property on_tap : Proc(Nil)? = nil

  def initialize(@label : String)
  def initialize(@label : String, &block : -> Nil)
end

Property	Type	Default	Description
label	String	(required)	Button display text
font	Font	system 17pt	Label font
foreground_color	Color	system blue	Label and tint color
disabled	Bool	false	Whether interaction is disabled
on_tap	Proc(Nil)?	nil	Callback invoked on tap

Example:

save = UI::Button.new("Save") { puts "Saved!"; nil }

delete = UI::Button.new("Delete")
delete.foreground_color = UI::Color.new(r: 1.0, g: 0.0, b: 0.0)
delete.on_tap = ->{ handle_delete; nil }

---

UI::VStack

File: src/ui/views/vstack.cr

Vertical stack layout.

class UI::VStack < UI::View
  property spacing : Float64 = 8.0
  property alignment : Alignment = Alignment::Center
  getter children : Array(View) = [] of View

  def initialize(@spacing : Float64 = 8.0, @alignment : Alignment = Alignment::Center)
  def <<(child : View) : self
end

---

UI::HStack

File: src/ui/views/hstack.cr

Horizontal stack layout.

class UI::HStack < UI::View
  property spacing : Float64 = 8.0
  property alignment : Alignment = Alignment::Center
  getter children : Array(View) = [] of View

  def initialize(@spacing : Float64 = 8.0, @alignment : Alignment = Alignment::Center)
  def <<(child : View) : self
end

---