Bridge UI

Rails + Inertia

Set up Bridge UI in a Ruby on Rails app with Inertia.js (Vue or React).

Bridge UI works with Ruby on Rails through Inertia.js (inertia_rails) and Vite (often via Vite Ruby).

Use the framework selector in the site header to switch between React and Vue on framework-specific steps below.

Install packages

Add Bridge UI and icons to your frontend. Packages are published on npm as 0.0.3.

bun add @bridge-ui/[email protected]
bun add @bridge-ui/[email protected]

App entry

Wire Bridge UI into your Inertia client entry:

import { createBridgeUI } from "@bridge-ui/vue";
import { createInertiaApp } from "@inertiajs/vue3";
import { createApp, h } from "vue";

createInertiaApp({
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(createBridgeUI())
      .mount(el);
  },
});

Bridge UI is provided from the layout—no extra plugin in the entry file:

import { createInertiaApp } from "@inertiajs/react";
import { createRoot } from "react-dom/client";

createInertiaApp({
  setup({ el, App, props }) {
    createRoot(el).render(<App {...props} />);
  },
});

Layout

Wrap your Inertia layout with BridgeUIProvider and BridgeUIHosts so imperative actions (useModalAction, useDialogAction, useSnackbarAction) work across pages.

<script setup lang="ts">
import { BridgeUIProvider } from "@bridge-ui/vue";
import { BridgeUIHosts } from "@bridge-ui/vue/Actions";
</script>

<template>
  <BridgeUIProvider :global="{}" :components="{}">
    <BridgeUIHosts
      :modal="{ modal: { transition: 'fade' } }"
      :dialog="{ modal: { transition: 'fade' } }"
      :snackbar="{ max: 3, timeout: 5000, position: 'bottom-center' }"
    >
      <slot />
    </BridgeUIHosts>
  </BridgeUIProvider>
</template>

import { BridgeUIProvider } from "@bridge-ui/react";
import { BridgeUIHosts } from "@bridge-ui/react/Actions";
import type { PropsWithChildren } from "react";

const Layout = ({ children }: PropsWithChildren) => (
  <BridgeUIProvider global={{}} components={{}}>
    <BridgeUIHosts
      modal={{ modal: { transition: "fade" } }}
      dialog={{ modal: { transition: "fade" } }}
      snackbar={{ max: 3, timeout: 5000, position: "bottom-center" }}
    >
      {children}
    </BridgeUIHosts>
  </BridgeUIProvider>
);

export default Layout;

Select async data

The Select component accepts an asyncData object with search and resolve callbacks. In Rails apps, these typically call JSON API endpoints via axios.

Below is a complete pattern you can copy: a route, a controller, and a small client helper.

Rails route

# config/routes.rb
get "/api/examples/users", to: "examples/user_selects#index"

Controller

The controller returns { label, value, description } objects compatible with Select options:

# app/controllers/examples/user_selects_controller.rb
class Examples::UserSelectsController < ApplicationController
  def index
    users = User.select(:id, :name, :email).order(:name)

    ids = Array(params[:ids]).compact_blank
    search = params[:search].to_s.strip

    users =
      if ids.any?
        users.where(id: ids)
      elsif search.present?
        users.where("name ILIKE :q OR email ILIKE :q", q: "%#{search}%")
      else
        users
      end

    render json: users.limit(20).map { |user|
      {
        value: user.id,
        label: user.name,
        description: user.email
      }
    }
  end
end

Query parameters:

Param Purpose
search Filter options while the user types
ids Resolve labels for already-selected values

Client helper

Create app/frontend/lib/asyncSelect.ts (path may vary with Vite Ruby):

import type { SelectAsyncData, SelectValue } from "@bridge-ui/core";
import axios from "axios";

export function asyncSelect(options: { url: string }): SelectAsyncData {
  const { url } = options;

  return {
    limit: 20,
    resolve: async (values: SelectValue[]) => {
      const { data } = await axios.get(url, {
        params: { ids: values },
        headers: { Accept: "application/json" },
      });

      return data;
    },
    search: async (query) => {
      const params: Record<string, string> = {};
      if (query) params.search = query;

      const { data } = await axios.get(url, {
        params,
        headers: { Accept: "application/json" },
      });

      return data;
    },
  };
}

Usage in a page

<script setup lang="ts">
import { asyncSelect } from "@/examples/core/integrations/asyncSelect";
import { Select } from "@bridge-ui/vue/Components/Select";
import { ref } from "vue";

const userId = ref(null);
</script>

<template>
  <Select
    label="User"
    v-model="userId"
    placeholder="Type to search users..."
    :async-data="asyncSelect({ url: '/api/examples/users' })"
  />
</template>

import { useState } from "react";

import { asyncSelect } from "@/examples/core/integrations/asyncSelect";
import { Select } from "@bridge-ui/react/Components/Select";

export default function UserSelect() {
  const [userId, setUserId] = useState<null | number | string>(null);

  return (
    <Select
      label="User"
      value={userId}
      onChange={setUserId}
      placeholder="Type to search users..."
      asyncData={asyncSelect({ url: "/api/examples/users" })}
    />
  );
}

asyncData implies searchable. Selected values are resolved through the same endpoint with ids when the page loads or when chips need labels.

Next steps