UI component constructors for the Dala framework.
Each function returns a node map compatible with Dala.Ui.Renderer. These can
be used directly or mixed freely — they produce the same map format.
# Native map literal
%{type: :text, props: %{text: "Hello"}, children: []}
# Component function (keyword list or map)
Dala.Ui.Widgets.text(text: "Hello")Both forms produce identical output and are accepted by Dala.Ui.Renderer.
Summary
Functions
Returns an :activity_indicator leaf node. Displays a circular loading spinner.
Returns a :app_bar leaf node. A top app bar with title and action icons.
Returns a :badge container node. Displays a numeric badge over its children.
Returns a :bottom_sheet container node. A slide-up panel anchored to the bottom.
Returns a :box container node. Children are stacked on top of each other (ZStack).
Returns a :button leaf node.
Returns a :camera_preview component node. Renders a live camera feed inline.
Returns a :card container node. A Material-style card with elevation and variants.
Returns a :carousel leaf node. A horizontally scrolling carousel of items.
Returns a :checkbox leaf node. A checkbox with an optional label.
Returns a :chip leaf node. A compact Material Design chip.
Returns a :column container node. Children are laid out vertically (VStack).
Returns a :date_picker leaf node. A date selection dialog.
Returns a :divider leaf node. A horizontal or vertical divider line.
Returns a :fab leaf node. A Floating Action Button.
Returns an :icon leaf node. Displays a platform-native icon.
Returns a :icon_button leaf node. A clickable icon button.
Returns an :image leaf node. Displays an image from a URL or local asset.
Returns a :list node. A data-driven list (FlatList equivalent).
Returns a :menu leaf node. A popup menu with selectable items.
Returns a :modal container node. Presents content above the enclosing view.
Returns a :native_view node that renders a platform-native component.
Returns a :nav_bar leaf node. A bottom navigation bar.
Returns a :nav_drawer leaf node. A side navigation drawer.
Returns a :nav_rail leaf node. A side navigation rail (for tablets/desktop).
Returns a :pressable container node. A pressable wrapper.
Returns a :progress_bar leaf node. Displays a progress bar.
Returns a :radio leaf node. A radio button within a group.
Returns a :refresh_control leaf node. Adds pull-to-refresh to ScrollView.
Returns a :row container node. Children are laid out horizontally (HStack).
Returns a :safe_area container node. Applies safe area insets.
Returns a :scroll container node. A scrollable view (ScrollView equivalent).
Returns a :search_bar leaf node. A search input bar with placeholder and callbacks.
Returns a :segmented_button leaf node. A segmented control with multiple segments.
Returns a :slider leaf node. A continuous range slider.
Returns a :snackbar leaf node. A transient message bar with an optional action.
Returns a :spacer leaf node. Flexible or fixed space.
Returns a :status_bar leaf node. Controls the status bar appearance.
Returns a :switch leaf node. A boolean toggle switch.
Returns a :tab_bar container node. A tab navigation bar.
Returns a :text leaf node.
Returns a :text_field leaf node. A single-line text input.
Returns a :time_picker leaf node. A time selection dialog.
Returns a :toggle leaf node. A boolean toggle switch.
Returns a :tooltip container node. Shows a tooltip over its children.
Returns a :video leaf node. An inline video player.
Returns a :webview component node. Renders a native web view inline.
Functions
Returns an :activity_indicator leaf node. Displays a circular loading spinner.
Props
:size—:smallor:large(default::small):color— spinner color (default: theme primary):animating— whether spinner is animating (default: true)
Returns a :app_bar leaf node. A top app bar with title and action icons.
Props
:title— string, app bar title:leading_icon— string, icon name for the leading navigation icon:on_leading—{pid, tag}tuple; fired when leading icon is tapped:trailing_actions— list of maps with:iconand:on_tap:background— background color:text_color— title and icon color:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.app_bar(
title: "My App",
leading_icon: "back",
on_leading: {self(), :back_pressed},
trailing_actions: [%{icon: "search", on_tap: {self(), :search}}]
)
Returns a :badge container node. Displays a numeric badge over its children.
Props
:count— integer, numeric badge value:color— badge background color:text_color— badge text color:visible— boolean, whether the badge is shown (default: true)
Examples
Dala.Ui.Widgets.badge([count: 5, color: :error], [
Dala.Ui.Widgets.icon(name: "notifications")
])
Returns a :bottom_sheet container node. A slide-up panel anchored to the bottom.
Props
:visible— boolean, whether the sheet is shown:on_dismiss—{pid, tag}tuple; fired when the sheet is dismissed:drag_indicator— boolean, show drag handle at top (default: true):peek_height— float, height of the sheet when partially visible:background— background color:corner_radius— rounded corners at the top
Examples
Dala.Ui.Widgets.bottom_sheet([visible: true, on_dismiss: {self(), :dismissed}, drag_indicator: true], [
Dala.Ui.Widgets.text(text: "Sheet content")
])
Returns a :box container node. Children are stacked on top of each other (ZStack).
Same props as column/2. Useful for overlays, badges, and absolute positioning.
Returns a :button leaf node.
Props
:text— button label (required). Also accepts:titlefor backward compatibility.:on_tap—{pid, tag}tuple; fired when button is pressed:disabled— boolean, disables the button (default: false):text_color— label color (accepts color tokens):text_size— font size:font_weight—"regular","medium","semibold","bold","light","thin":background— button background color (accepts color tokens):padding,:padding_top,:padding_right,:padding_bottom,:padding_left:corner_radius— rounded corners:fill_width— boolean, stretch to fill parent width (default: true from component defaults):accessibility_id— test identifier
Examples
Dala.Ui.Widgets.button(text: "Submit", on_tap: {self(), :submit})
Dala.Ui.Widgets.button(title: "OK", on_tap: {self(), :ok}, background: :primary)
Returns a :camera_preview component node. Renders a live camera feed inline.
Call Dala.Media.Camera.start_preview/2 before mounting this component, and
Dala.Media.Camera.stop_preview/1 when done.
Props
:facing—:back(default) or:front:width,:height— dimensions in dp/pts; omit to fill parent
Returns a :card container node. A Material-style card with elevation and variants.
Props
:elevation— float, shadow depth:variant—:filled,:outlined, or:elevated:background— background color:padding,:padding_top,:padding_right,:padding_bottom,:padding_left:border_color,:border_width— border styling:corner_radius— rounded corners:on_tap—{pid, tag}tuple; fired when card is tapped:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.card([variant: :elevated, elevation: 2.0, corner_radius: 12], [
Dala.Ui.Widgets.text(text: "Card content")
])
Returns a :carousel leaf node. A horizontally scrolling carousel of items.
Props
:data— enumerable of items to render:id— atom identifier for the carousel:on_page_change—{pid, tag}tuple; fired with new page index on swipe:loop— boolean, enables infinite looping (default: false):peek— float, peek width for adjacent items
Examples
Dala.Ui.Widgets.carousel(id: :photo_carousel, data: assigns.photos, on_page_change: {self(), :page_changed})
Returns a :checkbox leaf node. A checkbox with an optional label.
Props
:value— boolean, checked state (default: false):on_change—{pid, tag}tuple; fired with new boolean value on change:label— string, label text displayed beside the checkbox:color— color token for the checkbox tint:enabled— boolean, whether the checkbox is interactive (default: true):accessibility_id— test identifier
Examples
Dala.Ui.Widgets.checkbox(value: true, on_change: {self(), :agree_toggled}, label: "I agree")
Returns a :chip leaf node. A compact Material Design chip.
Props
:label— string, chip text (required):variant—:assist,:filter,:input, or:suggestion:selected— boolean, selected state (for filter chips):on_tap—{pid, tag}tuple; fired when chip is tapped:icon— string, icon name displayed before the label:on_remove—{pid, tag}tuple; fired when remove icon is tapped (input chips):enabled— boolean, whether the chip is interactive:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.chip(label: "Filter", variant: :filter, selected: true, on_tap: {self(), :chip_tapped})
Returns a :column container node. Children are laid out vertically (VStack).
Props
:gap— spacing between children (accepts spacing tokens like:space_md):padding,:padding_top,:padding_right,:padding_bottom,:padding_left:background— background color (accepts color tokens):border_color,:border_width— optional border:corner_radius— rounded corners:fill_width— boolean, stretch to fill parent width:on_tap,:on_long_press,:on_double_tap,:on_swipe*— gesture handlers:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.column([padding: :space_md, gap: :space_sm], [
Dala.Ui.Widgets.text(text: "Title"),
Dala.Ui.Widgets.text(text: "Subtitle")
])
Returns a :date_picker leaf node. A date selection dialog.
Props
:visible— boolean, whether the picker is shown:on_select—{pid, tag}tuple; fired with selected date string (ISO 8601):on_dismiss—{pid, tag}tuple; fired when the picker is dismissed:selected_date— string, initial date in ISO 8601 format:min_date— string, earliest selectable date:max_date— string, latest selectable date:title— string, optional title text
Examples
Dala.Ui.Widgets.date_picker(
visible: true,
on_select: {self(), :date_picked},
selected_date: "2025-01-15"
)
Returns a :divider leaf node. A horizontal or vertical divider line.
Props
:thickness— line thickness in pt (default: 1.0):color— divider color (accepts color tokens, default::border):padding— padding around the divider
Examples
Dala.Ui.Widgets.divider()
Dala.Ui.Widgets.divider(thickness: 2, color: :primary)
Returns a :fab leaf node. A Floating Action Button.
Props
:icon— string, icon name (required):on_tap—{pid, tag}tuple; fired when FAB is tapped:text— string, optional label for extended FAB:background— background color:color— icon color:corner_radius— rounded corners:elevation— float, shadow depth:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.fab(icon: "add", on_tap: {self(), :add_item})
Dala.Ui.Widgets.fab(icon: "edit", text: "Compose", on_tap: {self(), :compose})
Returns an :icon leaf node. Displays a platform-native icon.
Logical icon names are resolved to SF Symbols on iOS and Material Symbols on
Android. Unknown names pass through verbatim (power users can use raw SF Symbol
identifiers like "globe.americas.fill").
Props
:name— logical icon name or raw identifier (required):text_size— glyph size in sp:text_color— glyph tint color (accepts color tokens):padding,:background— layout props:on_tap,:on_long_press— gesture handlers:accessibility_id— test identifier (also used as accessibility label)
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
Examples
Dala.Ui.Widgets.icon(name: "settings", text_size: 24, text_color: :on_surface)
Dala.Ui.Widgets.icon(name: "chevron_right", on_tap: {self(), :navigate})
Returns a :icon_button leaf node. A clickable icon button.
Props
:icon— string, icon name (required):on_tap—{pid, tag}tuple; fired when button is tapped:selected— boolean, toggle state for toggle icon buttons:enabled— boolean, whether the button is interactive:color— icon color:background— background color:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.icon_button(icon: "favorite", on_tap: {self(), :favorite_tapped})
Returns an :image leaf node. Displays an image from a URL or local asset.
Props
:src— URL or local asset name (required):resize_mode—:cover(default),:contain,:stretch,:repeat:width,:height— dimensions in dp/pts; omit to auto-size:corner_radius— optional rounded corners:placeholder_color— color shown while loading:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.image(src: "https://example.com/photo.jpg", resize_mode: :cover, corner_radius: 12)
Returns a :list node. A data-driven list (FlatList equivalent).
Leverages Dala.Ui.List for rendering. Requires an :id prop to identify the list
for selection events and custom renderers.
Props
:data— enumerable of items to render (mapped to:items):id— atom identifier for the list (required for selection events):on_end_reached—{pid, tag}tuple; fired when list reaches end:scroll— boolean, enables scrolling (default: true)
For custom item rendering, register a renderer via Dala.Ui.List.put_renderer/3 in mount/3.
Examples
Dala.Ui.Widgets.list(id: :my_list, data: assigns.items)
# With custom renderer in mount/3:
# Dala.Ui.List.put_renderer(socket, :my_list, fn item -> ... end)
Returns a :modal container node. Presents content above the enclosing view.
Props
:visible— boolean, controls whether modal is shown (default: false):on_dismiss—{pid, tag}tuple; fired when user dismisses modal:presentation_style—:full_screen(default) or:page_sheet
Examples
Dala.Ui.Widgets.modal([visible: true, on_dismiss: {self(), :dismissed}], [
Dala.Ui.Widgets.text(text: "Modal content")
])
Returns a :native_view node that renders a platform-native component.
module must implement the Dala.Ui.NativeView behaviour and be registered
on the native side via dalaNativeViewRegistry. The :id must be unique
per screen — a duplicate raises at render time.
All other props are passed to mount/2 and update/2 on the component.
Example
Dala.Ui.Widgets.native_view(MyApp.ChartComponent, id: :revenue_chart, data: @points)
Returns a :pressable container node. A pressable wrapper.
Props
:on_press—{pid, tag}tuple; fired when pressed:on_long_press—{pid, tag}tuple; fired on long press
Examples
Dala.Ui.Widgets.pressable([on_press: {self(), :card_tapped}], [
Dala.Ui.Widgets.text(text: "Tap me")
])
Returns a :progress_bar leaf node. Displays a progress bar.
Props
:progress— float 0.0 to 1.0, current progress (default: 0.0):indeterminate— boolean, shows indeterminate spinner (default: false):color— progress bar color
Returns a :radio leaf node. A radio button within a group.
Props
:selected— boolean, whether this radio is selected:on_select—{pid, tag}tuple; fired when this radio is selected:label— string, label text displayed beside the radio:group— string, radio group name (radios in the same group are mutually exclusive):enabled— boolean, whether the radio is interactive:color— color token for the radio tint:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.radio(selected: true, on_select: {self(), :option_a}, label: "Option A", group: "choices")
Returns a :refresh_control leaf node. Adds pull-to-refresh to ScrollView.
Attach as a child of :scroll node. The scroll node handles the refresh gesture.
Props
:on_refresh—{pid, tag}tuple; fired when user pulls to refresh:refreshing— boolean, true while refresh is in progress:tint_color— color of the refresh spinner
Returns a :row container node. Children are laid out horizontally (HStack).
Same props as column/2.
Returns a :safe_area container node. Applies safe area insets.
Renders children within the safe area boundaries (avoiding notches, status bar, etc.).
Returns a :scroll container node. A scrollable view (ScrollView equivalent).
Props
:direction—:vertical(default) or:horizontal:shows_indicator— boolean, show scroll indicator (default: true):on_end_reached—{pid, tag}tuple; fired when scroll reaches bottom/end:on_scroll—{pid, tag}tuple; fired during scrolling with scroll position:padding,:background— layout props
Examples
Dala.Ui.Widgets.scroll([padding: :space_md], [
Dala.Ui.Widgets.text(text: "Long content...")
])
Returns a :search_bar leaf node. A search input bar with placeholder and callbacks.
Props
:placeholder— string, placeholder text when empty:text— string, current search text:on_change—{pid, tag}tuple; fired on every text change:on_submit—{pid, tag}tuple; fired when search is submitted:on_focus—{pid, tag}tuple; fired when the bar gains focus:active— boolean, whether the search bar is in active/expanded state:on_tap—{pid, tag}tuple; fired when the search bar is tapped:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.search_bar(placeholder: "Search...", on_change: {self(), :search_changed}, on_submit: {self(), :search_submitted})
Returns a :segmented_button leaf node. A segmented control with multiple segments.
Props
:segments— list of maps, each with:id,:label, and optional:icon:selected— the id of the currently selected segment:on_select—{pid, tag}tuple; fired with selected segment id:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.segmented_button(
segments: [%{id: "day", label: "Day"}, %{id: "week", label: "Week"}, %{id: "month", label: "Month"}],
selected: "week",
on_select: {self(), :range_changed}
)
Returns a :slider leaf node. A continuous range slider.
Props
:value— current value (default: 0.5):min_value— minimum value (default: 0.0):max_value— maximum value (default: 1.0):on_change—{pid, tag}tuple; fired with new float value on drag:color— slider tint color:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.slider(value: 0.5, min_value: 0, max_value: 100, on_change: {self(), :volume_changed})
Returns a :snackbar leaf node. A transient message bar with an optional action.
Props
:message— string, the message text (required):action_label— string, label for the optional action button:on_action—{pid, tag}tuple; fired when the action button is tapped:duration—:shortor:long:visible— boolean, whether the snackbar is shown
Examples
Dala.Ui.Widgets.snackbar(message: "Item deleted", action_label: "Undo", on_action: {self(), :undo})
Returns a :spacer leaf node. Flexible or fixed space.
Props
:size— fixed size in pt (omit for flexible spacer that fills available space)
Examples
Dala.Ui.Widgets.spacer() # flexible — fills available space
Dala.Ui.Widgets.spacer(size: 20) # fixed 20pt gap
Returns a :status_bar leaf node. Controls the status bar appearance.
Props
:bar_style—:default(dark text) or:light_content(light text):hidden— boolean, hides the status bar (default: false)
Returns a :switch leaf node. A boolean toggle switch.
Prefer toggle/1 for new code — it uses :on_change consistent with other
value widgets. This function is kept for backward compatibility.
Props
:value— boolean, on/off state (default: false):on_toggle—{pid, tag}tuple; fires{:toggle, tag, new_value}to handler:track_color— color when switch is on:thumb_color— color of the draggable thumb
Returns a :tab_bar container node. A tab navigation bar.
Props
:tabs— list of tab definitions, each a map with:id,:label, and optional:icon:active_tab— the id of the currently selected tab:on_tab_select—{pid, tag}tuple; fired with selected tab id string:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.tab_bar(
tabs: [
%{id: "home", label: "Home", icon: "home"},
%{id: "settings", label: "Settings", icon: "settings"}
],
active_tab: "home",
on_tab_select: {self(), :tab_changed}
)
Returns a :text leaf node.
Props
:text— the string to display (required):text_color— color value (accepts color tokens like:on_surface):text_size— font size (accepts size tokens like:xlor numeric sp):font_weight—"regular","medium","semibold","bold","light","thin":font_family— custom font family name (nil = system font):text_align—:left,:center,:right:italic— boolean:line_height— multiplier (e.g.1.5for 150% line height):letter_spacing— extra spacing in pt:padding,:padding_top,:padding_right,:padding_bottom,:padding_left:background— background color:corner_radius— rounded corners:fill_width— boolean, stretch to fill parent width:on_tap,:on_long_press,:on_double_tap— gesture handlers:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.text(text: "Hello")
Dala.Ui.Widgets.text(text: "Title", text_size: :xl, font_weight: "bold", text_color: :on_surface)
Returns a :text_field leaf node. A single-line text input.
Props
:text— initial/current text value:placeholder— placeholder text when empty:on_change—{pid, tag}tuple; fired on every text change with new value:on_focus—{pid, tag}tuple; fired when field gains focus:on_blur—{pid, tag}tuple; fired when field loses focus:on_submit—{pid, tag}tuple; fired when return key is pressed:on_compose—{pid, tag}tuple; IME composition events (CJK, etc.):keyboard_type—:default,:number,:decimal,:email,:phone,:url:return_key—:done,:next,:go,:search,:send:text_color,:text_size— typography:background,:padding,:corner_radius— layout:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.text_field(placeholder: "Enter name", on_change: {self(), :name_changed})
Dala.Ui.Widgets.text_field(keyboard_type: :email, return_key: :next, on_submit: {self(), :next_field})
Returns a :time_picker leaf node. A time selection dialog.
Props
:visible— boolean, whether the picker is shown:on_select—{pid, tag}tuple; fired with selected time string (HH:MM):on_dismiss—{pid, tag}tuple; fired when the picker is dismissed:selected_time— string, initial time in HH:MM format:title— string, optional title text
Examples
Dala.Ui.Widgets.time_picker(
visible: true,
on_select: {self(), :time_picked},
selected_time: "09:30"
)
Returns a :toggle leaf node. A boolean toggle switch.
Props
:value— boolean, on/off state (default: false):on_change—{pid, tag}tuple; fired with new boolean value on toggle:text— optional label text displayed beside the switch:track_color— color when switch is on:thumb_color— color of the draggable thumb:accessibility_id— test identifier
Examples
Dala.Ui.Widgets.toggle(value: true, on_change: {self(), :notifications_toggled}, text: "Notifications")
Returns a :tooltip container node. Shows a tooltip over its children.
Props
:text— string, tooltip text (required):position—:top,:bottom,:left, or:right
Examples
Dala.Ui.Widgets.tooltip([text: "Save changes", position: :top], [
Dala.Ui.Widgets.icon(name: "save")
])
Returns a :video leaf node. An inline video player.
Props
:src— video URL (required):autoplay— boolean, start playing immediately (default: false):loop— boolean, loop playback (default: false):controls— boolean, show playback controls (default: true):width,:height— dimensions in dp/pts; omit to fill parent
Examples
Dala.Ui.Widgets.video(src: "https://example.com/clip.mp4", autoplay: true, loop: true)
Returns a :webview component node. Renders a native web view inline.
The JS bridge is injected automatically — the page can call window.dala.send(data)
to deliver messages to handle_info({:webview, :message, data}, socket), and
Elixir can push to JS via Dala.WebView.post_message/2.
Props
:url— URL to load (required):allow— list of URL prefixes that navigation is permitted to (default: allow all). Blocked attempts arrive as{:webview, :blocked, url}inhandle_info.:show_url— show a native URL label above the WebView (default: false):title— static title label above the WebView; overrides:show_url:width,:height— dimensions in dp/pts; omit to fill parent