Components

DSL syntax

Screens are defined using the Spark DSL inside a dala do ... end block. UI components are declared as nested entities with keyword props:

defmodule MyApp.HomeScreen do
  use Dala.Spark.Dsl

  dala do
    attribute :count, :integer, default: 0

    screen name: :home do
      column padding: :space_md, gap: :space_sm do
        text "Hello", text_size: :xl
        button "Save", on_tap: :save
      end
    end
  end

  def handle_event(:save, _params, socket) do
    {:noreply, socket}
  end
end

You can also build component trees as plain maps — useful when constructing UI programmatically:

%{
  type:     :column,
  props:    %{padding: 16},
  children: [
    %{type: :text,   props: %{text: "Hello", text_size: :xl}, children: []},
    %{type: :button, props: %{text: "Save",  on_tap: {self(), :save}}, children: []}
  ]
}

The two styles are fully interchangeable — you can mix them freely in the same render/1 function.

Dala.Renderer serialises the component tree to binary via the custom binary protocol and passes it to the native side in a single NIF call. Compose (Android) and SwiftUI (iOS) handle diffing and rendering.

Prop values

Props accept:

• Integers and floats — used as-is (dp on Android, pt on iOS)
• Strings — used as-is
• Booleans — used as-is
• Color atoms (:primary, :blue_500, etc.) — resolved via the active theme and the base palette to ARGB integers. See Theming.
• Spacing tokens (:space_xs, :space_sm, :space_md, :space_lg, :space_xl) — scaled by theme.space_scale and resolved to integers.
• Radius tokens (:radius_sm, :radius_md, :radius_lg, :radius_pill) — resolved to integers from the active theme.
• Text size tokens (:xs, :sm, :base, :lg, :xl, :2xl, :3xl, :4xl, :5xl, :6xl) — scaled by theme.type_scale and resolved to floats.

Platform-specific props

Wrap props in :ios or :android to apply them only on that platform:

column padding: 12, ios: [padding: 20] do
  text "Content"
end

Layout components

:column

Stacks children vertically (VStack equivalent).

column padding: :space_md, gap: :space_sm, alignment: :center do
  text "Title"
  text "Subtitle"
end

:row

Lays out children horizontally (HStack equivalent).

To distribute children evenly across a row, give each child a weight prop (analogous to flex: 1 in CSS):

row fill_width: true do
  button "Cancel", on_tap: :cancel, weight: 1, background: :surface, text_color: :on_surface
  spacer size: 8
  button "Save", on_tap: :save, weight: 1
end

:box

A stacking container (ZStack equivalent). Children are layered on top of each other. Use it for overlays, badges, and absolute positioning.

box background: :surface, padding: :space_md, corner_radius: :radius_md do
  text "Card content"
end

:scroll

A scrolling container (ScrollView equivalent).

scroll padding: :space_md do
  text "Long content..."
end

:spacer

Inserts fixed space in a row or column, or fills available space when no size is given.

# Fixed gap:
spacer size: 16

# Push children to opposite ends of a row:
row do
  text "Left"
  spacer
  text "Right"
end

:safe_area

Renders children within safe area boundaries (avoiding notches, status bar, etc.).

safe_area do
  column padding: :space_md do
    text "Safe content"
  end
end

:pressable

A pressable wrapper. Makes any child tappable.

pressable on_press: {self(), :card_tapped} do
  text "Tap me"
end

List components

:list

A platform-native scrolling list optimised for rendering many rows efficiently. Prefer this over :scroll + :column for any list of more than ~20 items.

list :my_list, data: @items, on_end_reached: :load_more

Content components

:text

Displays a string.

text "Hello, world!"
text "Count: @count", text_size: :xl, text_color: :on_surface

:button

A tappable button. Has sensible defaults injected by the renderer (primary background, on_primary text, medium radius, fill width).

button "Save", on_tap: :save
button "Cancel", on_tap: :cancel, background: :surface, text_color: :on_surface
button "Edit", on_tap: :edit, variant: :outlined, icon: "edit"
button "Delete", on_tap: :delete, variant: :text, text_color: :error

:text_field

An editable text input. Has defaults injected by the renderer (surface_raised background, border, small radius).

text_field placeholder: "Enter name", on_change: :name_changed
text_field placeholder: "Password", secure: true, on_change: :password_changed
text_field placeholder: "Email", keyboard_type: :email, return_key: :next, on_submit: :next_field

:icon

Displays a platform-native icon. Logical icon names are resolved to SF Symbols on iOS and Material Symbols on Android.

Logical icon names: settings, back, forward, close, add, remove, edit, check, chevron_right, chevron_left, chevron_up, chevron_down, info, warning, error, search, trash, share, more, menu, refresh, favorite, favorite_filled, star, star_filled, user, home

icon name: "settings", text_size: 24, text_color: :on_surface
icon name: "chevron_right", on_tap: {self(), :navigate}

:divider

A horizontal or vertical divider line.

divider
divider thickness: 2, color: :primary

:image

Displays an image from a URL or local asset.

image src: "https://example.com/photo.jpg", resize_mode: :cover, corner_radius: 12

:video

An inline video player.

video src: "https://example.com/clip.mp4", autoplay: true, loop: true

:progress_bar

A progress bar (determinate or indeterminate).

progress_bar progress: 0.7, color: :primary
progress_bar indeterminate: true

:activity_indicator

A circular loading spinner.

activity_indicator size: :large, color: :primary

:toggle

A boolean switch. Delivers {:change, tag, value} to handle_event/3 where value is true or false.

toggle value: true, on_change: {self(), :notifications_toggled}, text: "Enable notifications"

def handle_event({:change, :notifications_toggled, enabled}, _params, socket) do
  {:noreply, Dala.Socket.assign(socket, :notifications_on, enabled)}
end

:slider

A continuous value input. Delivers {:change, tag, value} to handle_event/3 where value is a float.

slider value: 0.5, min_value: 0.0, max_value: 1.0, on_change: :volume_changed

def handle_event({:change, :volume_changed, value}, _params, socket) do
  {:noreply, Dala.Socket.assign(socket, :volume, value)}
end

:tab_bar

A tab navigation bar.

tab_bar(
  tabs: [
    %{id: "home", label: "Home", icon: "home"},
    %{id: "settings", label: "Settings", icon: "settings"}
  ],
  active_tab: "home",
  on_tab_select: {self(), :tab_changed}
)

:refresh_control

Pull-to-refresh control for scroll views.

scroll padding: :space_md do
  refresh_control on_refresh: {self(), :refresh}, refreshing: @refreshing
  # content...
end

Selection components

:checkbox

A checkbox for selecting one or more items from a list. Maps to Checkbox on Compose and Toggle on SwiftUI.

checkbox value: true, on_change: {self(), :agree_toggled}, label: "I agree"

checkbox value: false, label: "Accept terms", color: :primary, enabled: false

:radio

A radio button within a group. Only one radio in a group can be selected. Maps to RadioButton on Compose and Toggle with style on SwiftUI.

radio selected: true, on_select: {self(), :option_a}, label: "Option A", group: "choices"

:chip

A compact Material Design chip. Maps to FilterChip, InputChip, etc. on Compose.

chip label: "Filter", variant: :filter, selected: true, on_tap: {self(), :chip_tapped}
chip label: "Tag", variant: :input, on_remove: {self(), :tag_removed}

:carousel

A horizontally scrolling carousel of items. Maps to HorizontalPager on Compose.

carousel id: :photo_carousel, data: @photos, on_page_change: {self(), :page_changed}

Communication components

:snackbar

A transient message bar with an optional action. Maps to Snackbar on Compose.

snackbar message: "Item deleted", action_label: "Undo", on_action: {self(), :undo}

:tooltip

Shows a tooltip over its children. Maps to Tooltip on Compose and help modifier on SwiftUI.

tooltip text: "Save changes", position: :top do
  icon name: "save"
end

Action components

:fab

A Floating Action Button. Maps to FloatingActionButton on Compose.

fab icon: "add", on_tap: {self(), :add_item}
fab icon: "edit", text: "Compose", on_tap: {self(), :compose}

:icon_button

A clickable icon button. Maps to IconButton on Compose.

icon_button icon: "favorite", on_tap: {self(), :favorite_tapped}
icon_button icon: "bookmark", selected: true, enabled: false

:segmented_button

A segmented control with multiple segments. Maps to SegmentedButton on Compose.

segmented_button(
  segments: [
    %{id: "day", label: "Day"},
    %{id: "week", label: "Week"},
    %{id: "month", label: "Month"}
  ],
  selected: "week",
  on_select: {self(), :range_changed}
)

Navigation components

:app_bar

A top app bar with title and action icons. Maps to TopAppBar on Compose.

app_bar(
  title: "My App",
  leading_icon: "back",
  on_leading: {self(), :back_pressed},
  trailing_actions: [%{icon: "search", on_tap: {self(), :search}}]
)

:nav_bar

A bottom navigation bar. Maps to NavigationBar on Compose.

nav_bar(
  items: [
    %{id: "home", label: "Home", icon: "home"},
    %{id: "profile", label: "Profile", icon: "user"}
  ],
  active: "home",
  on_select: {self(), :tab_changed}
)

:nav_drawer

A side navigation drawer. Maps to ModalNavigationDrawer on Compose.

nav_drawer(
  visible: true,
  on_dismiss: {self(), :drawer_dismissed},
  items: [%{id: "home", label: "Home", icon: "home"}],
  active: "home",
  on_select: {self(), :nav_changed}
)

:nav_rail

A side navigation rail (for tablets/desktop). Maps to NavigationRail on Compose.

nav_rail(
  items: [
    %{id: "home", label: "Home", icon: "home"},
    %{id: "settings", label: "Settings", icon: "settings"}
  ],
  active: "home",
  on_select: {self(), :rail_changed}
)

:menu

A popup menu with selectable items. Maps to DropdownMenu on Compose.

menu(
  items: [%{label: "Edit", action: :edit}, %{label: "Delete", action: :delete}],
  visible: true,
  on_select: {self(), :menu_selected}
)

:date_picker

A date selection dialog. Maps to DatePicker on Compose and UIDatePicker on SwiftUI.

date_picker(
  visible: true,
  on_select: {self(), :date_picked},
  selected_date: "2025-01-15"
)

:time_picker

A time selection dialog. Maps to TimePicker on Compose and UIDatePicker on SwiftUI.

time_picker(
  visible: true,
  on_select: {self(), :time_picked},
  selected_time: "09:30"
)

:search_bar

A search input bar with placeholder and callbacks. Maps to SearchBar on Compose and UISearchBar on SwiftUI.

search_bar(placeholder: "Search...", on_change: {self(), :search_changed}, on_submit: {self(), :search_submitted})

Event handler conventions

In DSL style, event handlers are atoms that map directly to handle_event/3 clauses:

dala do
  screen name: :home do
    button "Save", on_tap: :save
  end
end

def handle_event(:save, _params, socket) do
  {:noreply, socket}
end

Event routing

All events are delivered to the screen process via handle_event/3. Every on_tap, on_change, on_select, and similar handler sends its message directly to the screen process — regardless of how deeply the component is nested in the tree.

Screen registration with Dala.App.screens/1

Register screen modules in your app's navigation/1 callback using screens/1. This validates at compile time that modules are valid Dala.Screen modules:

defmodule MyApp do
  use Dala.App

  def navigation(_platform) do
    screens([MyApp.HomeScreen, MyApp.SettingsScreen])
    stack(:home, root: MyApp.HomeScreen)
  end
end

See Navigation for full details.