In Hotwire Native, how does a bridge component put a native Save button on a habit form, and what happens in app builds that lack the component?
answer
- two halves: Stimulus side and native side
- static component = "form" matches native name
- this.send(event, data, callback)
- native reply(to:) runs the callback
- unsupported: component stays disabled, web UI remains
basics
~20 sA web BridgeComponent (a Stimulus controller with static component = "form") messages a same-named native component, which shows a Save button and replies when tapped so the web callback submits the form. Builds without it keep the HTML button.
solid answer
~40 sThe web half extends `BridgeComponent` from `@hotwired/hotwire-native-bridge`, which is a Stimulus `Controller`, so it attaches through `data-controller` like any other, conventionally under `controllers/bridge/` as `bridge--form`. It declares `static component = "form"` and, when its submit target connects, calls `this.send("connect", { submitTitle }, () => target.click())`. The native half subclasses `BridgeComponent` in Swift or Kotlin with the name `form`, is registered with `Hotwire.registerBridgeComponents`, receives the message in `onReceive`, adds a navigation-bar button and, when tapped, calls `reply(to: "connect")` (`replyTo` on Android), which runs the web callback. The app registers its supported components with the page's bridge and lists them in its user agent; a web component the build does not support stays disabled, so the ordinary HTML button keeps working, which makes the feature safe for old builds and browsers.
code
erb · 5 lines<%= form_with model: @habit, data: { controller: "bridge--form" } do |form| %>
<%= form.text_field :name %>
<%= form.submit "Save habit",
data: { bridge__form_target: "submit", bridge_title: "Save" } %>
<% end %>go deeper
Recall that a bridge component pairs a Stimulus-based web controller with native code so a page can show native controls.
Explain the matching component name, this.send with a callback, the native reply and how components are registered on each platform.
Design components as progressive enhancement: degrade for browsers and old builds, and hide web controls only when support is confirmed.
Decide which interactions justify two native implementations and a release cycle, and keep the component catalogue small and shared.
## What a bridge component is A **bridge component** lets a web page drive a piece of native UI. Hotwire Native screens are web views, so without a bridge the native shell cannot know that the page holds a form, a menu or a share action. Bridge components, formerly the separate **Strada** library and now built into Hotwire Native, solve this with two cooperating halves that share a name: - a **web component**: a Stimulus controller extending `BridgeComponent` from `@hotwired/hotwire-native-bridge`; - a **native component**: a Swift or Kotlin class extending the library's `BridgeComponent`. ## The web half ```javascript // app/javascript/controllers/bridge/form_controller.js import { BridgeComponent, BridgeElement } from "@hotwired/hotwire-native-bridge" export default class extends BridgeComponent { static component = "form" static targets = ["submit"] submitTargetConnected(target) { const submitButton = new BridgeElement(target) this.send("connect", { submitTitle: submitButton.title }, () => target.click()) } } ``` - Because it is a Stimulus controller, it attaches with `data-controller="bridge--form"` on the habit `<form>` and gets targets and lifecycle callbacks. - `static component` is the name the native side must use. - `this.send(event, data, callback)` posts a JSON message; the callback runs when native code replies to that event. - `BridgeElement` reads bridge attributes: `title` comes from `data-bridge-title`, then `aria-label`, then the element's text. - `this.enabled` tells the controller whether the current app supports the component; `data-controller-optout-ios` or `-android` opts one element out per platform. ## The native half On iOS the component overrides the class name and handles messages: 1. `class var name` returns `"form"`. 2. `onReceive(message:)` reads `submitTitle` and adds a `UIBarButtonItem` to the screen's navigation bar. 3. When the button is tapped, `reply(to: "connect")` sends a reply, and the web callback calls `target.click()`, submitting the form through Turbo as usual. Android mirrors this with `onReceive(message)` and `replyTo("connect")`. Each platform registers its components at start-up: `Hotwire.registerBridgeComponents([FormComponent.self])` on iOS, `Hotwire.registerBridgeComponents(BridgeComponentFactory("form", ::FormComponent))` on Android. ## Old builds and browsers The native app announces which components it supports: it registers them with the page's bridge adapter and also appends `bridge-components: [form menu]` to its user agent. That makes bridge components **progressive enhancement**: | client | result | |---|---| | browser | no native bridge; the component is not enabled and the HTML Save button is used | | app build without `form` | the component is not supported; the HTML button is used | | app build with `form` | the native button appears; the page can hide its own button | So shipping the web half first is safe: nothing changes until a build with the native half reaches users. Hiding the HTML button should key off support, not off `hotwire_native_app?` alone, or old builds lose their only Save button. ## Messages in both directions The pairing is a small message protocol rather than shared code: 1. The web component calls `this.send(event, data, callback)` with any event name and JSON data; `connect` is just the convention for "I have appeared". 2. The native component reads `message.event` and decodes `message.data()` into a struct (iOS) or data class (Android). 3. Native code replies with `reply(to:)` or `replyTo`, optionally with data, and the web callback receives that reply. 4. More events can follow: a form component may send `submitDisabled` and `submitEnabled` as validation changes, so the native button greys out with the HTML one. Because the web half is a Stimulus controller, it also disconnects with the page, and the native half has view lifecycle hooks such as `onViewWillDisappear`, so each side can clean up when the screen goes away. ## When to reach for one Bridge components suit **native chrome around web content**: navigation-bar buttons, overflow menus, action sheets, share sheets, permission prompts. They are small and composable, but each one is native code in two languages and ships only with an app release, so prefer plain web UI until a control genuinely needs to feel native.
- Why should the page hide its HTML Save button only when the component is supported?Browsers and app builds without the `form` component never show a native button, so the HTML button is their only way to submit. Keying the hiding on component support, rather than on being inside any native app, keeps old builds usable.
- Why is the web half a Stimulus controller?`BridgeComponent` extends Stimulus' `Controller`, so it attaches through `data-controller`, connects and disconnects with the DOM across Turbo visits, and uses targets such as `submitTargetConnected` to send its message when the button appears.
- Bridge components need the separate Strada package installed in the app
- The web and native halves can use different component names
- A bridge component works in every installed app build as soon as the web half deploys
- Bridge components replace the whole web screen with a native one
- The native button submits the form by posting directly to Rails, bypassing the page