Bridge UI

Django + Inertia

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

Bridge UI works with Django through Inertia.js (inertia-django) and a Vite-powered frontend.

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 (typically under resources/js/ or static/js/ depending on your Vite layout):

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 Django apps, these typically call JSON API endpoints via axios.

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

Django route

# urls.py
from django.urls import path
from .views import UserSelectView

urlpatterns = [
    path("api/examples/users/", UserSelectView.as_view(), name="user-select"),
]

View

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

# views.py
from django.contrib.auth import get_user_model
from django.db.models import Q
from django.http import JsonResponse
from django.views import View

User = get_user_model()


class UserSelectView(View):
    def get(self, request):
        ids = [value for value in request.GET.getlist("ids") if value]
        search = request.GET.get("search", "").strip()

        queryset = User.objects.all().order_by("name")

        if ids:
            queryset = queryset.filter(pk__in=ids)
        elif search:
            queryset = queryset.filter(
                Q(name__icontains=search) | Q(email__icontains=search)
            )

        data = [
            {
                "value": user.pk,
                "label": user.get_full_name() or user.get_username(),
                "description": user.email,
            }
            for user in queryset[:20]
        ]

        return JsonResponse(data, safe=False)

Query parameters:

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

Client helper

Create resources/js/lib/asyncSelect.ts (path may vary with your Vite layout):

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