Styling & Native Rendering

This page maps every Mob component and style prop to its native counterpart on iOS (SwiftUI) and Android (Jetpack Compose). Use it when you need to understand platform behaviour, look up what constraints apply, or reach for a platform-specific override.

Mob does not wrap a web renderer — you are writing directly to SwiftUI and Compose. That means native look-and-feel, native performance, and native constraints.

Component → native widget

Platform docs:

• iOS SwiftUI: developer.apple.com/documentation/swiftui/views-and-controls
• Android Compose: developer.android.com/develop/ui/compose/components

Common layout props

These props apply to every component via nodeModifier (Android) and view modifiers (iOS).

iOS reference: SwiftUI Layout Android reference: Compose modifiers

Ordering note

On both platforms, background is applied before padding so the color fills the full padded box. Corner radius clips after padding so the rounded mask covers the entire padded area. Changing this order visually by hand (e.g. via platform overrides) is unsupported and will produce inconsistent results across platforms.

Typography props (:text and :button)

iOS font reference: Font (SwiftUI) Android font reference: Typography (Compose)

line_height difference

SwiftUI's .lineSpacing adds extra space between lines, not total line height. Mob converts the multiplier to extra spacing as (multiplier - 1.0) × font_size, matching Compose's lineHeight behaviour as closely as possible. For very tight values (multiplier < 1.0) results will differ between platforms — test on both.

Custom fonts

Drop .ttf / .otf files into priv/fonts/ in your Mix project. mix mob.deploy --native copies them into the correct platform directories and patches Info.plist for iOS. Reference them by PostScript name:

%{type: :text, props: %{text: "Hello", font: "Inter-Regular", text_size: :base}, children: []}

iOS requires the PostScript name (visible in Font Book → ⌘I). Android derives the resource name automatically from the filename (Inter-Regular.ttf → inter_regular), but Mob normalises the name before sending it to the NIF so you can use the same string on both platforms.

Color props

Color values are resolved in this order:

1. Semantic theme token (:primary, :surface, :on_surface, etc.) — resolved via the active Mob.Theme
2. Palette atom (:blue_500, :gray_200, etc.) — resolved from the built-in palette
3. Raw ARGB integer (0xFFFF5733) — used as-is
4. Unknown atom — serialised as a string; the native side treats it as a no-op color

iOS color rendering: all ARGB integers are passed as UIColor(argb:) via the NIF and converted to Color(_:) in SwiftUI. Android: ARGB integers are passed as Long and converted with Color(long).

iOS reference: Color (SwiftUI) Android reference: Color (Compose)

Input props (:text_field)

iOS reference: TextField (SwiftUI) Android reference: TextField (Compose)

iOS keyboard toolbar

iOS automatically shows a "Done" button in a keyboard toolbar above the keyboard for all text fields. This lets users dismiss the keyboard without triggering on_submit. There is no equivalent on Android — the IME action button handles both submit and dismiss.

Image props (:image)

iOS reference: AsyncImage (SwiftUI) Android reference: Coil

Scroll props (:scroll)

Android's verticalScroll modifier also applies .imePadding() so the keyboard does not obscure text fields inside a scroll view.

Video props (:video)

Android note: The Android video player is currently a stub. Full playback requires adding ExoPlayer (now bundled as androidx.media3:media3-exoplayer) to android/app/build.gradle:

implementation "androidx.media3:media3-exoplayer:1.3.1"
implementation "androidx.media3:media3-ui:1.3.1"

iOS reference: AVPlayerViewController Android reference: Media3 ExoPlayer

Tab bar props (:tab_bar)

iOS tab icons are SF Symbols — pass the symbol name as a string (e.g. "house", "person.fill"). See SF Symbols.

Android tab icons use Material icons. The same SF Symbol names work as a best-effort match; unrecognised names fall back to a circle. See Material Symbols.

Platform-specific overrides

Any prop can be overridden per-platform using nested :ios and :android keys:

props: %{
  padding:    12,
  ios:        %{padding: 20},       # iOS sees 20; Android sees 12
  android:    %{corner_radius: 4},  # Android gets extra radius; iOS doesn't
}

The unmatched platform's block is silently dropped before serialisation. Use this sparingly — prefer semantic tokens and let the platform render naturally.

Component defaults

The renderer injects these defaults for missing styling props. Explicit props always win.

All other components have no injected defaults — unstyled components use the platform's own defaults.

Toggle and slider props

:toggle

:slider

Human Interface Guidelines

For design decisions not covered here, refer to the platform design systems directly:

• Apple Human Interface Guidelines
• Material Design 3