DEV Community: sxq

Flow Render: Render UI Components Like Calling an Async Functions

sxq — Fri, 07 Aug 2026 10:37:38 +0000

Flow Render provides a Promise-based approach to rendering UI. It lets you render components as if calling async functions, await their results, and resume the same async flow.

It consolidates interaction logic scattered across state, callbacks, and component hierarchies into linear async/await control flow. Business workflows and UI components each remain highly cohesive, while Promise results establish a clear boundary between them, reducing coupling and keeping complex interactions focused, readable, and maintainable.

const confirmed = await render(ConfirmDialog, {
  title: 'Delete your workspace?'
})

if (!confirmed) return

await deleteWorkspace()

Use Flow Render when code genuinely needs to pause for a person:

Confirming a destructive action
Completing a form in a dialog
Choosing an account, plan, or destination
Accepting a permission request
Moving through a multi-step workflow
Recovering from an interrupted or failed operation

Flow Render focuses on interaction flows. Your screens, local state, server state, and routing stay where they already belong.

One minute demo
The missing await
The problem
The Flow Render model
Before and after
Quick start
Real-world examples
Choosing a renderer
API reference
Design philosophy
Comparison
Best practices
Advanced usage
FAQ
Framework support
Contributing

One minute demo

The complete React setup is two pieces: mount a Viewport once, then await a component from an event handler.

1. Install

npm install @flow-render/react

2. Mount a viewport

Place Viewport inside your application providers, near the root of the tree.

import { Viewport } from '@flow-render/react'

export function App() {
  return (
    <>
      <AppProviders>
        <Routes />
        <Viewport />
      </AppProviders>
    </>
  )
}

3. Make a dialog resolve a value

import type { PromiseResolvers } from '@flow-render/react'

type ConfirmDialogProps = PromiseResolvers<boolean> & {
  title: "string"
  description?: string
}

export function ConfirmDialog({
  title,
  description,
  resolve,
  reject,
}: ConfirmDialogProps) {
  return (
    <dialog open aria-labelledby="confirm-title">
      <h2 id="confirm-title">{title}</h2>
      {description && <p>{description}</p>}

      <footer>
        <button type="button" onClick={() => resolve(false)}>
          Cancel
        </button>
        <button type="button" onClick={() => resolve(true)}>
          Confirm
        </button>
        <button type="button" onClick={() => reject(new Error('Dismissed'))}>
          Dismiss
        </button>
      </footer>
    </dialog>
  )
}

4. Await it

import { render } from '@flow-render/react'

async function handleDelete() {
  const confirmed = await render(ConfirmDialog, {
    title: "'Delete this project?',"
    description: 'This cannot be undone.'
  })

  if (!confirmed) return

  await deleteProject()
}

That is the whole idea. render() adds the component to the mounted viewport and returns a Promise. Calling resolve(value) settles that Promise with value; calling reject(reason) rejects it. When the Promise settles, Flow Render removes the component.

The missing await

JavaScript already gives asynchronous operations a direct, readable shape:

const response = await fetch('/api/projects')
const project = await response.json()

await animation.finished
await sleep(300)

But UI is often expressed as disconnected state transitions:

setConfirmDialogOpen(true)

That line does not say what happens next. The continuation lives elsewhere: in a callback, an effect, a prop chain, a reducer branch, or a state machine transition.

User interaction is asynchronous too. A person sees a UI, decides, and eventually produces one of several outcomes. Flow Render lets that interaction use the same control-flow primitive as the rest of modern JavaScript:

const answer = await askUser()

const confirmed = await render(ConfirmDialog, { title: 'Ship this release?' })

if (!confirmed) return

await publishRelease()

This is not a claim that every component should be awaited. A persistent sidebar, inline editor, sortable table, or page-level filter is usually ordinary stateful UI. The useful boundary is narrower:

Await UI when the next step of an async flow depends on a bounded user interaction finishing.

The problem

Consider a typical destructive action. The happy path is tiny: ask, wait, delete. The state-driven version must distribute that path over several places.

function ProjectActions({ projectId }: { projectId: string }) {
  const [confirmOpen, setConfirmOpen] = useState(false)
  const [isDeleting, setIsDeleting] = useState(false)
  const [error, setError] = useState<Error | null>(null)

  async function handleConfirm() {
    setIsDeleting(true)
    setError(null)

    try {
      await deleteProject(projectId)
      setConfirmOpen(false)
    } catch (error) {
      setError(error as Error)
    } finally {
      setIsDeleting(false)
    }
  }

  return (
    <>
      <button onClick={() => setConfirmOpen(true)}>Delete project</button>

      <ConfirmDialog
        open={confirmOpen}
        busy={isDeleting}
        error={error}
        onCancel={() => setConfirmOpen(false)}
        onConfirm={handleConfirm}
      />
    </>
  )
}

There is nothing inherently wrong with this code. React state is the right tool for long-lived, interactive screens. The friction appears when an event starts a short-lived interaction with a result and then needs to continue. The original story is split across state declarations, event handlers, props, and cleanup.

Flow Render keeps the orchestration together while leaving the dialog itself a normal component:

async function handleDelete(projectId: string) {
  const confirmed = await render(ConfirmDialog, {
    title: 'Delete project?',
    description: 'All project data will be permanently removed.'
  })

  if (!confirmed) return

  await deleteProject(projectId)
}

The difference becomes more meaningful as a flow grows. A sequence of dialog, form, permission check, and network request reads from top to bottom rather than from state transition to state transition.

The Flow Render model

Flow Render has three moving parts.

Part	Responsibility
`render(Component, props)`	Creates one short-lived render task and returns its Promise.
`Viewport`	Renders pending tasks at a chosen place in the application tree.
`resolve` / `reject`	Props injected into a Promise-aware component so it can finish the task.

sequenceDiagram
  participant H as Event handler
  participant R as render()
  participant V as Viewport
  participant U as User

  H->>R: render(ConfirmDialog, props)
  R->>V: add ConfirmDialog
  V->>U: show dialog
  U->>V: click Confirm
  V->>R: resolve(true)
  R-->>H: Promise resolves with true
  H->>H: continue flow

The component is still a framework component. It can use your design system, hooks, context, CSS, accessibility primitives, and animation library. Flow Render only owns its temporary mounting and the Promise boundary.

Resolve values, not side effects

A Promise-aware UI component should express its outcome through resolve or reject.

type PlanPickerProps = PromiseResolvers<{ planId: string }> & {
  plans: Array<{ id: string; name: string }>
}

function PlanPicker({ plans, resolve, reject }: PlanPickerProps) {
  return (
    <section aria-label="Choose a plan">
      {plans.map((plan) => (
        <button key={plan.id} onClick={() => resolve({ planId: plan.id })}>
          Choose {plan.name}
        </button>
      ))}
      <button onClick={() => reject(new Error('No plan selected'))}>
        Close
      </button>
    </section>
  )
}

The caller gets a typed value and owns what happens next:

const { planId } = await render(PlanPicker, { plans })
await changeSubscription(planId)

This makes transient components easier to reuse: the picker chooses a plan; it does not also know how every caller updates billing, routing, analytics, or notifications.

Two integration styles

Executor mode is the recommended default. Declare resolve and reject in the component props. Flow Render injects them when the component is rendered.

type NameEditorProps = PromiseResolvers<string> & {
  initialValue: string
}

function NameEditor({ initialValue, resolve, reject }: NameEditorProps) {
  const [name, setName] = useState(initialValue)

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        resolve(name.trim())
      }}
    >
      <label>
        Project name
        <input value={name} onChange={(event) => setName(event.target.value)} />
      </label>
      <button type="button" onClick={() => reject(new Error('Editing cancelled'))}>
        Cancel
      </button>
      <button type="submit">Save</button>
    </form>
  )
}

Adapter mode is for an existing component whose callback props you cannot or do not want to change.

type LegacyConfirmProps = {
  open: boolean
  title: string
  onCancel: () => void
  onConfirm: () => void
}

function LegacyConfirmDialog(props: LegacyConfirmProps) {
  return (
    <dialog open={props.open}>
      <p>{props.title}</p>
      <button onClick={props.onCancel}>Cancel</button>
      <button onClick={props.onConfirm}>Confirm</button>
    </dialog>
  )
}

const confirmed = await render<LegacyConfirmProps, boolean>(
  LegacyConfirmDialog,
  (resolve) => ({
    open: true,
    title: 'Archive this project?',
    onCancel: () => resolve(false),
    onConfirm: () => resolve(true)
  })
)

Adapter mode is deliberately a bridge. It lets Flow Render work with a component library or legacy component while preserving its existing API.

Before and after

A form modal

Without a Promise boundary, a parent often needs state for both visibility and the eventual form value.

const [editOpen, setEditOpen] = useState(false)
const [pendingProfile, setPendingProfile] = useState<Profile | null>(null)

function handleEdit() {
  setEditOpen(true)
}

function handleProfileSaved(profile: Profile) {
  setEditOpen(false)
  setPendingProfile(profile)
}

useEffect(() => {
  if (!pendingProfile) return

  void saveProfile(pendingProfile)
  setPendingProfile(null)
}, [pendingProfile])

With Flow Render, the form result is simply a value.

async function handleEdit() {
  const profile = await render(ProfileEditor, { initialProfile: currentProfile })
  await saveProfile(profile)
}

A guarded navigation

State-driven code usually needs a destination stored separately while a dialog is open.

const [nextPath, setNextPath] = useState<string | null>(null)

function requestNavigation(path: string) {
  if (!isDirty) {
    navigate(path)
    return
  }

  setNextPath(path)
  setLeaveDialogOpen(true)
}

function confirmNavigation() {
  setLeaveDialogOpen(false)
  if (nextPath) navigate(nextPath)
  setNextPath(null)
}

With Flow Render, the destination stays local to the flow that needs it.

async function requestNavigation(path: string) {
  if (!isDirty) {
    navigate(path)
    return
  }

  const shouldLeave = await render(DiscardChangesDialog)

  if (shouldLeave) navigate(path)
}

A short workflow

The linear version makes the product decision points visible.

async function inviteMember() {
  const member = await render(MemberFormDialog)

  const role = await render(RolePickerDialog, {
    email: member.email
  })

  const confirmed = await render(ConfirmDialog, {
    title: `Invite ${member.email} as ${role.name}?`
  })

  if (!confirmed) return

  await sendInvite({ ...member, roleId: role.id })
}

No reducer state is needed merely to remember which step comes next. Each component remains independently testable and responsible for one interaction.

Quick start (React)

This guide uses React because it is the most common starting point. The same model is available for Vue, Preact, Svelte, and Solid.

Install the package

npm install @flow-render/react

Or with another package manager:

pnpm add @flow-render/react
yarn add @flow-render/react
bun add @flow-render/react

Mount `Viewport` once

The default render function uses the default Viewport exported by the package. Mount that viewport in a part of your tree that remains available for the interactions you want to run.

import { Viewport } from '@flow-render/react'

export function Root() {
  return (
    <ThemeProvider>
      <AuthProvider>
        <App />
        <Viewport />
      </AuthProvider>
    </ThemeProvider>
  )
}

Do not place the viewport outside providers that your dialogs rely on. A component rendered by Flow Render appears under Viewport, so it receives the context available at that point in the tree.

Build one awaitable component

Add PromiseResolvers<Value> to the props. Its resolve callback accepts the value returned to the caller; reject rejects the pending Promise.

import { useState } from 'react'
import type { PromiseResolvers } from '@flow-render/react'

type QuantityDialogProps = PromiseResolvers<number> & {
  initialQuantity: number
}

export function QuantityDialog({
  initialQuantity,
  resolve,
  reject,
}: QuantityDialogProps) {
  const [quantity, setQuantity] = useState(initialQuantity)

  return (
    <dialog open>
      <form
        onSubmit={(event) => {
          event.preventDefault()
          resolve(quantity)
        }}
      >
        <label>
          Quantity
          <input
            type="number"
            min="1"
            value={quantity}
            onChange={(event) => setQuantity(Number(event.target.value))}
          />
        </label>
        <button type="button" onClick={() => reject(new Error('Quantity not selected'))}>
          Cancel
        </button>
        <button type="submit">Continue</button>
      </form>
    </dialog>
  )
}

Await it from an event handler

import { render } from '@flow-render/react'

async function handleAddToCart() {
  const quantity = await render(QuantityDialog, {
    initialQuantity: 1
  })

  await addToCart({ sku: 'starter-kit', quantity })
}

render() is most natural in a function already allowed to be asynchronous: a button handler, mutation callback, route guard, command handler, or an application service called from the client.

Handle dismissal intentionally

There are two good conventions. Pick one per component family and document it for your team.

Resolve a neutral value when cancellation is an expected product choice.

type ConfirmDialogProps = PromiseResolvers<boolean>

function ConfirmDialog({ resolve }: ConfirmDialogProps) {
  return (
    <dialog open>
      <button onClick={() => resolve(false)}>Cancel</button>
      <button onClick={() => resolve(true)}>Confirm</button>
    </dialog>
  )
}

Reject when a caller must distinguish a completed interaction from dismissal or interruption.

try {
  const profile = await render(ProfileEditor)
  await saveProfile(profile)
} catch (error) {
  reportDismissal(error)
}

Do not reject simply to model a normal “No” answer. A value such as false, undefined, or a discriminated result often produces clearer caller code.

Real-world examples

The examples below are intentionally small. They show where the Promise boundary belongs; the components can use any UI library or visual style.

Confirm a destructive action

async function handleRemoveMember(member: Member) {
  const confirmed = await render(ConfirmDialog, {
    title: `Remove ${member.name}?`,
    description: 'They will lose access immediately.'
  })

  if (!confirmed) return

  await removeMember(member.id)
  toast.success(`${member.name} was removed`)
}

Create a resource in a modal

async function handleCreateProject() {
  const draft = await render(ProjectFormDialog, {
    initialValues: {
      name: '',
      visibility: 'private'
    }
  })

  const project = await createProject(draft)
  navigate(`/projects/${project.id}`)
}

The form owns validation and editing state. The caller owns the network request and navigation because those are the next steps in the flow.

Require login before continuing

async function handleExport() {
  if (!session.user) {
    const authenticated = await render(LoginDialog, {
      redirectTo: location.pathname
    })

    if (!authenticated) return
  }

  await exportReport()
}

LoginDialog can resolve a boolean, a user object, or an auth result. Return the smallest value the caller needs.

Ask for a permission

async function enableNotifications() {
  const approved = await render(NotificationPermissionDialog)

  if (!approved) return

  const permission = await Notification.requestPermission()

  if (permission === 'granted') {
    await subscribeToNotifications()
  }
}

The product explanation is UI; the browser permission request is an asynchronous platform operation. They compose naturally.

Select a payment method, then pay

async function checkout(invoice: Invoice) {
  const paymentMethod = await render(PaymentMethodPicker, {
    methods: invoice.availablePaymentMethods
  })

  const confirmed = await render(ConfirmPaymentDialog, {
    amount: invoice.total,
    paymentMethod
  })

  if (!confirmed) return

  await payInvoice({ invoiceId: invoice.id, paymentMethodId: paymentMethod.id })
}

Run a multi-step wizard

async function createWorkspace() {
  const details = await render(WorkspaceDetailsStep)
  const members = await render(InviteMembersStep, { workspaceName: details.name })
  const plan = await render(PlanPicker)

  const workspace = await createWorkspace({
    ...details,
    memberEmails: members.map((member) => member.email),
    planId: plan.id
  })

  navigate(`/workspaces/${workspace.id}`)
}

For a tightly coupled wizard with a shared back button and persistent draft state, one stateful wizard component can be a better fit. Use separate awaited steps when each interaction has a distinct, reusable result and the orchestration benefits from being visible in one function.

Guard unsaved changes

async function requestCloseEditor() {
  if (!editor.isDirty) {
    closeEditor()
    return
  }

  const action = await render(UnsavedChangesDialog)

  if (action === 'save') {
    await editor.save()
  }

  if (action === 'discard' || action === 'save') {
    closeEditor()
  }
}

A discriminated result makes multiple choices explicit.

type UnsavedAction = 'save' | 'discard' | 'stay'
type UnsavedChangesDialogProps = PromiseResolvers<UnsavedAction>

Retry a failed operation

async function publishWithRecovery(post: DraftPost) {
  try {
    await publishPost(post)
  } catch (error) {
    const nextAction = await render(PublishFailedDialog, { error })

    if (nextAction === 'retry') {
      await publishPost(post)
    }

    if (nextAction === 'save-draft') {
      await saveDraft(post)
    }
  }
}

Pick a destination for an upload

async function handleUpload(file: File) {
  const folder = await render(FolderPickerDialog, {
    initialFolderId: currentFolder.id
  })

  await uploadFile({ file, folderId: folder.id })
}

Finish onboarding

async function completeOnboarding() {
  const goal = await render(GoalPicker)
  const preferences = await render(NotificationPreferences)

  await updateOnboarding({ goal, preferences })
  navigate('/home')
}

The code resembles the product journey because it is the product journey.

Choosing a renderer

Flow Render provides three renderer scopes. Choose the lifetime that matches the UI being launched.

Renderer	Create it with	Best for
Default renderer	`render` and `Viewport` exports	Application-wide dialogs, pickers, and flows.
Local renderer	`useRenderer()`	UI that should disappear with one page, panel, or feature.
Custom renderer	`createRenderer()`	Component libraries or subsystems that own their own rendering entry point.

Default renderer

The default renderer is ready to use after its matching Viewport is mounted.

import { render, Viewport } from '@flow-render/react'

export function App() {
  return (
    <>
      <Routes />
      <Viewport />
    </>
  )
}

export async function openGlobalConfirm() {
  return render(ConfirmDialog, { title: 'Continue?' })
}

Use it for application-level interactions that should survive a particular page component unmounting.

Local renderer

useRenderer() gives a component a renderer bound to its own lifetime.

import { useRenderer } from '@flow-render/react'

function BillingPanel() {
  const [render, Viewport] = useRenderer()

  async function editInvoice() {
    const update = await render(InvoiceEditorDialog)
    await updateInvoice(update)
  }

  return (
    <section>
      <button onClick={editInvoice}>Edit invoice</button>
      <Viewport />
    </section>
  )
}

When the local viewport unmounts, unfinished tasks in that renderer are rejected with a cancellation error. This prevents temporary UI from leaking after its owner has gone away.

import { isCancelError, useRenderer } from '@flow-render/react'

function SearchPanel() {
  const [render, Viewport] = useRenderer()

  async function chooseFilter() {
    try {
      const filter = await render(FilterPicker)
      applyFilter(filter)
    } catch (error) {
      if (isCancelError(error)) return
      throw error
    }
  }

  return <><button onClick={chooseFilter}>Filter</button><Viewport /></>
}

Custom renderer

createRenderer() creates a separate render function and Viewport pair. This is useful when a library wants to expose a focused API without coupling consumers to the app-wide renderer.

import { createRenderer } from '@flow-render/react'

const [renderBillingUi, BillingViewport] = createRenderer()

export function BillingProvider({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <BillingViewport />
    </>
  )
}

export function openUpgradeDialog() {
  return renderBillingUi(UpgradeDialog)
}

This keeps the library's implementation detail behind its own openUpgradeDialog() function.

API reference

The public API is intentionally small. The React package exports the following primitives:

import {
  createRenderer,
  isCancelError,
  render,
  useRenderer,
  Viewport,
  type PromiseResolvers,
  type RenderOptions
} from '@flow-render/react'

`render`

render(Component, propsOrAdapter?, options?) => Promise<Value>

Renders Component into the associated viewport and returns a Promise for its result.

const name = await render(NameEditor, {
  initialValue: 'Untitled project'
})

For a Promise-aware component, the plain object contains every prop except resolve and reject; Flow Render supplies those callbacks.

type NameEditorProps = PromiseResolvers<string> & {
  initialValue: string
}

When a component does not expose resolver props, pass an adapter instead.

const option = await render<ExistingPickerProps, Option>(ExistingPicker, (resolve, reject) => ({
  options,
  onSelect: resolve,
  onClose: () => reject(new Error('Picker closed'))
}))

`PromiseResolvers<Value>`

interface PromiseResolvers<Value = unknown> {
  readonly resolve: (value: Value) => void
  readonly reject: (reason?: unknown) => void
}

Add this type to component props to have Value inferred at the call site.

type ColorPickerProps = PromiseResolvers<{ hex: string }> & {
  initialHex: string
}

async function chooseColor() {
  const color = await render(ColorPicker, { initialHex: '#0ea5e9' })
  // color is { hex: string }
}

For a component that only confirms completion, use PromiseResolvers<void>.

type NoticeProps = PromiseResolvers<void> & { message: string }

function Notice({ message, resolve }: NoticeProps) {
  return <button onClick={() => resolve()}>{message}</button>
}

`Viewport`

Viewport is the mount point for the default renderer. Render it in your framework tree before calling the default render function.

import { Viewport } from '@flow-render/react'

function RootLayout() {
  return (
    <Providers>
      <App />
      <Viewport />
    </Providers>
  )
}

It renders the pending components directly. It does not impose a portal, overlay, or visual system. That is deliberate: your dialog component decides how it looks and behaves.

`useRenderer`

useRenderer() => [render, Viewport]

Creates one renderer pair for the current component. Use it when temporary UI should be owned by a local feature.

const [render, Viewport] = useRenderer()

See Local renderer for a complete example.

`createRenderer`

createRenderer() => [render, Viewport]

Creates an independent renderer pair outside a component. Use it to encapsulate a subsystem or reusable package.

const [renderNotifications, NotificationsViewport] = createRenderer()

The renderNotifications function only renders into NotificationsViewport.

`RenderOptions`

interface RenderOptions {
  exitDelay?: number
}

Pass exitDelay in milliseconds when a component needs to remain mounted briefly after it resolves or rejects so its exit animation can run.

await render(FadeOutDialog, null, { exitDelay: 180 })

The Promise settles immediately. exitDelay delays DOM removal only; it does not delay the caller's next line of code.

`isCancelError`

isCancelError(error) => boolean

When a viewport unmounts with pending render tasks, Flow Render rejects those tasks with a cancellation error. Check it when local renderer cancellation is an expected lifecycle event.

try {
  await render(ShortLivedDialog)
} catch (error) {
  if (isCancelError(error)) return

  throw error
}

isCancelError is for lifecycle cancellation. A component calling reject() with its own error preserves that error.

Design philosophy

Flow control is not screen state

React and other UI frameworks excel at deriving UI from state. Flow Render does not try to replace that model. It adds a convenient representation for a different concern: a short-lived interaction whose result determines what an asynchronous operation does next.

Use state for:

Persistent page data
Inputs that change while a screen remains mounted
Visual toggles and layout
Server cache and mutation status
Long-running processes shown over time

Use an awaited interaction for:

A question with a bounded answer
A modal form that returns one result
A picker that returns one selected value
A gate in a user-initiated workflow
A short sequence whose next step depends on the prior answer

The two models compose. An awaited ProfileEditor can have rich local state, validation, async autocomplete, and its own child components. The parent just receives the completed profile.

Components remain normal components

Flow Render does not require a special component base class, code generation, global singleton outside your framework, or a new templating syntax. A component receives props and renders UI. The only optional convention is accepting resolve and reject props.

That matters because your existing UI can participate through adapter mode. Your component library stays useful; you add a Promise boundary where it helps orchestration.

The caller owns the next step

A dialog should be able to answer “what did the user choose?” without also knowing whether the caller will navigate, call an API, invalidate a cache, record analytics, or open another dialog. Those decisions belong to the flow owner.

const decision = await render(AccessRequestDialog, { request })

if (decision === 'approve') {
  await approveAccess(request.id)
  analytics.track('access_approved')
}

This keeps UI units reusable and keeps product logic readable in one place.

Cancellation is lifecycle, not an afterthought

Temporary UI must not outlive the tree responsible for it. When a local or custom viewport unmounts, unfinished tasks are rejected. A caller can explicitly handle that expected case with isCancelError.

Comparison

Flow Render is not a replacement for every common UI architecture. It is one small tool for a specific shape of problem.

Approach	Strong fit	Trade-off for short-lived UI flows
Local component state	Persistent or colocated UI	The continuation can spread across handlers, effects, and prop callbacks.
Callback props	Small parent-child interactions	Nested or cross-cutting flows become difficult to follow.
Global modal store	A shared dialog shell	Flow state often moves into action names and callback registries.
State machine	Complex, long-lived state with explicit transitions	Can be more ceremony than a bounded “ask, wait, continue” interaction needs.
Flow Render	User-initiated UI that returns one result	Requires a mounted viewport and deliberate error/cancellation handling.

Flow Render and React state

Use React state inside a dialog. Use Flow Render at the boundary between the dialog's eventual outcome and the caller's continuation.

function InviteDialog({ resolve }: PromiseResolvers<Invite>) {
  const [email, setEmail] = useState('')
  const [role, setRole] = useState<Role>('member')

  return (
    <form onSubmit={(event) => {
      event.preventDefault()
      resolve({ email, role })
    }}>
      {/* ordinary controlled form fields */}
    </form>
  )
}

Flow Render and state machines

State machines are a strong choice when a process is long-lived, concurrent, visualized as a state graph, or must remain resumable across navigation. A payment lifecycle, media upload queue, or editor with background synchronization may deserve an explicit machine.

For a short user-triggered interaction, this can be enough:

const confirmed = await render(ConfirmDialog)
if (confirmed) await submit()

Start with the smallest model that makes the flow understandable. Introduce a state machine when the domain has genuine state-machine complexity, not just because a dialog has two buttons.

Why is this not built into React?

React deliberately models UI as a function of state. That is a good foundation. Flow Render is a tiny complementary layer that turns a temporary render task into a Promise so application code can express sequential interactions directly.

It does not replace React's rendering model, component composition, transitions, Suspense, routing, or state libraries. It gives a focused answer to a focused question: how should code wait for a UI interaction to finish?

Best practices

Keep flows close to the initiating action

Put the orchestration in the event handler, mutation callback, command, or service that owns the intent.

async function handleTransfer() {
  const recipient = await render(RecipientPicker)
  const amount = await render(AmountDialog, { recipient })
  await transfer({ recipientId: recipient.id, amount })
}

Avoid storing intermediate flow values in unrelated global state just because multiple components participate.

Return useful, small values

Prefer a value that states the interaction result.

type DeleteResult = 'confirm' | 'cancel'
type DeleteDialogProps = PromiseResolvers<DeleteResult>

Avoid returning UI objects, setters, or callbacks when a plain product value will do.

Make normal cancellation a value when possible

For a confirmation dialog, false is often simpler than rejecting:

const confirmed = await render(ConfirmDialog)
if (!confirmed) return

Reserve rejection for interruption, failed validation strategies that escape the component, or a dismissal contract that the caller needs to distinguish.

Keep the component responsible for accessibility

Flow Render controls mounting, not focus management or dialog semantics. Use the accessible dialog, focus trap, escape-key behavior, labels, and design-system primitives appropriate to your application.

Put `Viewport` under the right providers

The viewport determines which context temporary components can read.

<QueryClientProvider client={queryClient}>
  <ThemeProvider>
    <App />
    <Viewport />
  </ThemeProvider>
</QueryClientProvider>

Do not await from render

Start interactions from an event or an effect with a well-defined lifecycle, not while React is rendering.

function DeleteButton() {
  async function handleClick() {
    const confirmed = await render(ConfirmDialog)
    if (confirmed) await deleteCurrentProject()
  }

  return <button onClick={handleClick}>Delete</button>
}

Handle local renderer cancellation

If a local viewport can disappear before the interaction completes, catch cancellation at the boundary where that is expected.

try {
  const choice = await localRender(ChoiceDialog)
  applyChoice(choice)
} catch (error) {
  if (!isCancelError(error)) throw error
}

Advanced usage

Preserve an exit animation

When a component resolves, the caller should normally continue immediately. If the component has an exit animation, keep it mounted for the animation duration with exitDelay.

async function handleArchive() {
  const confirmed = await render(ArchiveDialog, null, {
    exitDelay: 220
  })

  if (confirmed) await archiveProject()
}

The dialog's CSS or animation library controls the animation itself. Flow Render only schedules its later removal.

Wrap a component-library dialog

Adapter mode is useful for component libraries that expose callbacks instead of resolver props.

type DesignSystemDialogProps = {
  open: boolean
  onOpenChange: (open: boolean) => void
  onAccept: () => void
}

const accepted = await render<DesignSystemDialogProps, boolean>(
  DesignSystemConfirm,
  (resolve) => ({
    open: true,
    onOpenChange: (open) => {
      if (!open) resolve(false)
    },
    onAccept: () => resolve(true)
  })
)

Make sure only one callback represents each outcome. If onOpenChange(false) and onAccept() can both run, have the component or adapter normalize that behavior just as you would in ordinary component usage.

Create a domain-specific UI service

A small wrapper can give callers a stable, meaningful API while hiding the raw component.

export async function confirmProjectDeletion(project: Project) {
  return render(ConfirmDialog, {
    title: `Delete ${project.name}?`,
    description: 'This cannot be undone.'
  })
}

async function handleDelete(project: Project) {
  if (await confirmProjectDeletion(project)) {
    await deleteProject(project.id)
  }
}

The wrapper is valuable when it eliminates repeated product language or enforces a shared interaction contract. Do not create a generic abstraction merely to hide one render() call.

Compose flows with ordinary async functions

An awaited UI flow is just an async function, so it composes with normal client-side services.

async function collectAndCreateProject() {
  const details = await render(ProjectDetailsDialog)
  const template = await render(TemplatePicker)

  return createProject({
    ...details,
    templateId: template.id
  })
}

async function handleNewProject() {
  const project = await collectAndCreateProject()
  navigate(`/projects/${project.id}`)
}

Isolate a subsystem

Use a custom renderer when a subsystem needs its own lifecycle and public entry points.

const [renderSupport, SupportViewport] = createRenderer()

export function SupportProvider({ children }: { children: React.ReactNode }) {
  return <>{children}<SupportViewport /></>
}

export function openContactSupport() {
  return renderSupport(ContactSupportDialog)
}

This pattern is especially useful in shared product modules: consumers mount one provider and call a narrow function, while the module decides which UI it renders.

Common mistakes

Calling the default renderer without mounting its viewport

The default render function needs the matching default Viewport mounted in the application tree.

// Required somewhere in the active client tree.
<Viewport />

For a local or custom renderer, render the viewport returned by that same renderer pair.

Treating every UI change as a flow

This is not a replacement for useState.

// Good: a bounded interaction produces one value.
const color = await render(ColorPicker)

// Usually not a Flow Render task: a persistent screen preference.
setSidebarCollapsed(true)

Hiding important errors

If a component rejects for a meaningful failure, let the caller handle or rethrow it. Only swallow cancellation errors that are expected because a local viewport unmounted.

try {
  await render(RequiredForm)
} catch (error) {
  if (isCancelError(error)) return
  throw error
}

Letting a component perform every next step

If a modal both chooses a value, calls an API, navigates, invalidates caches, and dispatches analytics, it is hard to reuse. Let it return the choice. Let the caller continue the business flow.

Using `exitDelay` as an async wait

exitDelay keeps the node mounted after settlement. It does not block await render().

const result = await render(Dialog, null, { exitDelay: 300 })
// This runs immediately after resolve/reject, while the dialog may animate out.

FAQ

Does Flow Render replace React state?

No. React state remains the right model for persistent, reactive UI. Flow Render is for short-lived interactions that return a result to an async flow.

Does Flow Render replace a state machine?

No. State machines are excellent for long-lived, concurrent, or explicitly modeled domain processes. Flow Render is lighter-weight for bounded UI interactions where the next step can be expressed as sequential code.

Can I use my existing dialog component?

Yes. Use adapter mode to map its callbacks to resolve and reject.

await render<ExistingDialogProps, Result>(ExistingDialog, (resolve, reject) => ({
  ...existingProps,
  onComplete: resolve,
  onDismiss: () => reject(new Error('Dismissed'))
}))

Does it work with context and providers?

Yes. Render Viewport under the providers your temporary components need. Components rendered through that viewport receive the context available at that location.

What happens when a viewport unmounts?

Pending tasks for that renderer are rejected with a cancellation error and removed. Use isCancelError when that lifecycle event is expected.

Can a dialog return a typed object?

Yes. The result type is inferred from PromiseResolvers<Value>.

type AddressDialogProps = PromiseResolvers<Address>

const address = await render(AddressDialog)

Can I render more than dialogs?

Yes. A component can be a sheet, picker, full-screen step, inline panel, or any other UI that has a bounded completion result. The viewport decides where it mounts; the component decides its presentation.

Why use rejection at all?

Use rejection when the caller should distinguish normal completion from dismissal, interruption, or an error. For a simple yes/no question, resolving false is often easier.

Is `exitDelay` required for animations?

Only when the component must remain mounted after it resolves or rejects so an exit animation can finish. Without it, Flow Render removes the component at settlement.

Framework support

Flow Render uses the same Promise-based model across five UI frameworks. This README uses React for the main examples; each package includes framework-specific setup and examples.

Framework	Package	Package guide
React	`@flow-render/react`	React README
Vue	`@flow-render/vue`	Vue README
Preact	`@flow-render/preact`	Preact README
Svelte	`@flow-render/svelte`	Svelte README
Solid	`@flow-render/solid`	Solid README

Install the package for your framework:

npm install @flow-render/react
npm install @flow-render/vue
npm install @flow-render/preact
npm install @flow-render/svelte
npm install @flow-render/solid

The public concepts are the same: mount a viewport, render a component, await its result. Follow the package guide for framework-specific component syntax and setup.

When Flow Render is a good fit

Use it when all of these are true:

A user action starts a flow.
The flow needs a bounded UI interaction.
That interaction has a result, cancellation, or failure.
The next line of code depends on that outcome.

const destination = await render(DestinationPicker)
await moveItems({ itemIds, destinationId: destination.id })

Consider another pattern when the UI is persistent, heavily concurrent, resumable across sessions, or needs a durable model of many independent transitions.

Github

Flow Render

Flow Render: Render components in async flows — make your UI awaitable.

sxq — Fri, 13 Mar 2026 08:47:55 +0000

Flow Render provides a Promise-based UI rendering approach that allows you to render components like calling
asynchronous functions and wait for user interaction results.

It reorganizes scattered states, callbacks, and component hierarchies into a linear async/await control flow, making
complex interaction logic intuitive and easy to maintain.

const result = await render(Component)

✨ Features

Promise-driven UI rendering: Wait for component results like calling async functions
Any component can be Promise-enabled: New or existing components can be integrated without intrusive modifications
Centralized control flow: Write interaction logic sequentially, avoiding scattered states and nested callbacks
Complete context inheritance: Automatically preserves application context like theme, i18n, store
Isolated instances, destroyed after use: Each render is an independent instance without interference, component state automatically resets
Supports global and local rendering: Can be mounted at the app root or bound to local component lifecycle

📦 Framework Support

Framework	Package
React	`@flow-render/react` (also supports React Native)
Vue	`@flow-render/vue`
Preact	`@flow-render/preact`
Svelte	`@flow-render/svelte`
Solid	`@flow-render/solid`

🚀 Quick Start (React)

Step 1: Install

npm i @flow-render/react

Step 2: Mount the Viewport

Place a <Viewport/> at the root of your application. All dynamically rendered components will appear here.

import { Viewport } from '@flow-render/react'

function App () {
  return (
    <>
      <YourApp/>
      <Viewport/> {/* Dynamic components are rendered here */}
    </>
  )
}

Step 3: Define Components

Flow Render supports two ways to write components; you can choose based on your scenario.

Executor Mode (Recommended)

Components directly declare and use resolve/reject callbacks, similar to the new Promise((resolve, reject) => ...)
executor style.

import { type PromiseResolvers } from '@flow-render/react'

interface Props extends PromiseResolvers<boolean> {
  title: string
}

function ConfirmDialog ({ title, resolve, reject }: Props) {
  return (
    <dialog open>
      <div>{title}</div>
      <div>
        <button onClick={() => resolve(true)}>Yes</button>
        <button onClick={() => resolve(false)}>No</button>
        <button onClick={() => reject(new Error('Cancel'))}>Cancel</button>
      </div>
    </dialog>
  )
}

Callbacks are automatically injected when rendering:

import { render } from '@flow-render/react'

const result = await render(ConfirmDialog, {
  title: 'Are you sure?'
})

Adapter Mode (Flexible and Powerful)

Adapter mode allows you to dynamically associate props of any component with a Promise. You simply provide a function
that receives resolve and reject and returns the component's props. This approach not only works with existing
components but also enables more complex logic, such as determining props based on external data, conditional rendering,
dynamic bindings, etc.

interface Props {
  title: string
  onYes: () => void
  onNo: () => void
  onCancel: () => void
}

function ConfirmDialog (props: Props) {
  return (
    <dialog open>
      <div>{props.title}</div>
      <div>
        <button onClick={props.onYes}>Yes</button>
        <button onClick={props.onNo}>No</button>
        <button onClick={props.onCancel}>Cancel</button>
      </div>
    </dialog>
  )
}

When rendering with adapter mode, you establish the connection between the Promise and component callbacks via an
adapter function:

import { render } from '@flow-render/react'

const result = await render(ConfirmDialog, (resolve, reject) => {
  return {
    title: 'Are you sure?',
    onYes: () => resolve(true),
    onNo: () => resolve(false),
    onCancel: () => reject(),
  }
})

📌 Lifecycle Explanation

By default, the lifecycle of dynamically rendered components from render() does not follow the calling component,
but follows the global Viewport.

This means:

Even if the component that triggered the render is unmounted, the dynamic component can still exist
Suitable for global modals, confirmation dialogs, selectors, async guided flows, etc.

If you want dynamic components to be automatically destroyed when the current page or component unmounts, use a local
renderer.

Local Renderer

Using useRenderer() creates a local renderer bound to the current component's lifecycle.

Applicable scenarios:

Page-level modals
Interactions that need to be destroyed with a local area
Custom rendering positions

import { useRenderer } from '@flow-render/react'

function Page () {
  const [render, Viewport] = useRenderer()

  return (
    <div>
      <button onClick={() => render(ConfirmDialog)}>Open</button>
      <Viewport/>
    </div>
  )
}

When Page unmounts, any unfinished rendering tasks in the local renderer will also be terminated.

Custom Renderer

When developing component libraries or business subsystems, you may want to expose your own rendering entry
point instead of having users depend on the default renderer. In this case, use createRenderer() to create an
independent instance.

// your-lib/index.ts

import { createRenderer } from '@flow-render/react'

const [render, Viewport] = createRenderer()

export function LibProvider (props) {
  return (
    <>
      {props.children}
      <Viewport/>
    </>
  )
}

export function openDialog () {
  return render(Dialog)
}

Then, users only need to use the Provider and corresponding methods provided by your library, without any knowledge of
Flow Render's internals:

import { LibProvider, openDialog } from 'your-lib'

function App () {
  return (
    <LibProvider>
      <UserApp/>
      <button onClick={() => openDialog()}>Open</button>
    </LibProvider>
  )
}

This encapsulates the rendering capability inside the library, providing a more stable and unified API externally.

Cancelling Rendering

Manual Cancellation

In some advanced scenarios, you may need to interrupt the UI flow externally, for example:

Auto-close on timeout
Terminate on route change
User actively cancels the entire flow

Since render() returns a standard Promise, you can expose cancellation capability through the adapter:

let cancel: () => void

const promise = render(Component, (resolve, reject) => {
  cancel = () => reject(new Error('Cancelled'))

  return {
    resolve,
    reject,
  }
})

// Call when needed
cancel()

Automatic Cancellation

When a Viewport unmounts (e.g., global Viewport destroyed with the app, or local Viewport destroyed with its
component), all unfinished rendering tasks will be automatically rejected. If necessary, you can use isCancelError to
determine whether an error was caused by automatic cancellation.

import { render, isCancelError } from '@flow-render/react'

try {
  await render(Component)
} catch (error) {
  if (isCancelError(error)) {
    // Handle automatic cancellation
    return
  }

  throw error
}

Use Cases

Flow Render is particularly suitable for the following interactions:

Confirmation dialogs / Alert boxes
Form modals
Selectors
Guided workflows
Login interception
Permission confirmation
Any UI logic that requires "waiting for the user to complete a step before continuing"

For example, you can write previously scattered interactions as a linear flow:

async function postForm () {
  // Step 1: Confirmation
  const confirmed = await render(ConfirmDialog, {
    title: 'Confirm submission?'
  })

  if (!confirmed) {
    return
  }

  // Step 2: Fill form
  const formData = await render(FormDialog)

  // Step 3: Submit
  await submit(formData)
}

Compared to traditional state-driven approaches, this method is easier to read, reuse, and maintain.

Design Philosophy

Flow Render is not meant to replace the existing component model of frameworks, but rather to provide a more natural
expression for asynchronous UI interaction flows:

Dynamically render on demand
Display UI and wait for user operations
Continue later logic after getting results

These steps can be organized within the same async/await code block.

For interactions that cross components, hierarchies, and flows, this approach is often more intuitive.

Github: https://github.com/flow-render/flow-render

Exploring AutoAPI: An Automation Tool to Simplify Frontend Development

sxq — Mon, 25 Nov 2024 01:15:21 +0000

Managing API requests and response types is a critical task in modern frontend development. AutoAPI offers an automated solution to streamline this process and boost development efficiency, leveraging OpenAPI/Swagger documentation. This article delves into the features, working principles, use cases, and how AutoAPI addresses common development challenges.

Core Features of AutoAPI

1. Atomic Request Methods

One of AutoAPI's core features is its atomic request methods. Each API request method is an independent module that can be invoked anywhere within the project. This design not only aids in modularizing and maintaining the code but also supports tree shaking, thereby reducing bundle size and enhancing application performance.

Advantages:

Modular Design: Facilitates easier code management and refactoring.
Performance Optimization: Minimizes unnecessary code bundling through tree shaking.

2. Automatic Type Generation

Traditionally, developers manually write TypeScript types for API requests and responses, a task that is both tedious and error-prone. AutoAPI automatically generates these types by parsing OpenAPI/Swagger documentation, ensuring accuracy and consistency in type definitions.

Advantages:

Error Reduction: Automatic type generation reduces the risk of manual errors.
Efficiency: Saves developers time by eliminating the need for manual type maintenance.

3. Type Inference

AutoAPI features type inference, which can automatically derive TypeScript types from JSON data. This is particularly useful when documentation is incomplete or lacks structural definitions.

Advantages:

Flexibility: Ensures type safety even in the absence of comprehensive documentation.
Adaptability: Quickly generates type definitions based on actual data.

4. Granular Control

AutoAPI offers extensive configuration options, allowing developers to exert granular control over the generated code. This includes settings for filtering, grouping, naming conventions, and type structures.

Advantages:

Customization: Developers can tailor the generated code structure to meet project requirements.
Flexible Configuration: Accommodates specific needs across different projects.

5. Adapter Mechanism

Through its adapter mechanism, AutoAPI can adapt to various business scenarios. Developers can create custom adapters to modify the logic for generating request methods, ensuring alignment with project-specific requirements.

Advantages:

Business Adaptation: Ensures generated request methods align with specific business logic.
Extensibility: Easily add new adapters to meet evolving needs.

6. Support for SSR

In server-side rendering (SSR) scenarios, AutoAPI supports context parameter passing. Developers can add parameter pass-through logic within adapters to ensure API requests function correctly in both server and client environments.

Advantages:

Consistency: Ensures request consistency across different rendering environments.
Flexibility: Supports complex SSR scenario requirements.

7. Excellent API Structure Management

AutoAPI supports managing API structures across multiple documents and groups. Developers can organize and manage multiple API documents within a project, enhancing code maintainability and readability.

Advantages:

Organization: Clear API structure management enhances code readability.
Scalability: Easily manage multiple API documents in large projects.

Use Cases

1. Rapid Prototyping

In rapid prototyping, AutoAPI helps teams quickly generate API request methods and type definitions, reducing initial development time.

2. Type Management in Large Projects

In large projects, manually managing type definitions can lead to errors and inconsistencies. AutoAPI's automation ensures consistency and accuracy in type definitions.

3. Dynamic API Documentation

In projects with frequently changing API documentation, AutoAPI can automatically adjust the generated code to remain in sync with the latest documentation.

Conclusion

AutoAPI is a powerful and flexible tool that significantly enhances frontend development efficiency and code quality. By automating the generation of request methods and type definitions, it helps developers reduce manual workload, minimize errors, and adapt to complex business scenarios. If you're seeking a solution to simplify API management, AutoAPI is undoubtedly worth exploring.

For more information about AutoAPI, visit the AutoAPI GitHub repository.

DEV Community: sxq

Flow Render: Render UI Components Like Calling an Async Functions

Contents

One minute demo

1. Install

2. Mount a viewport

3. Make a dialog resolve a value

4. Await it

The missing await

The problem

The Flow Render model

Resolve values, not side effects

Two integration styles

Before and after

A form modal

A guarded navigation

A short workflow

Quick start (React)

Install the package

Mount Viewport once

Build one awaitable component

Await it from an event handler

Handle dismissal intentionally

Real-world examples

Confirm a destructive action

Create a resource in a modal

Require login before continuing

Ask for a permission

Select a payment method, then pay

Run a multi-step wizard

Guard unsaved changes

Retry a failed operation

Pick a destination for an upload

Finish onboarding

Choosing a renderer

Default renderer

Local renderer

Custom renderer

API reference

render

PromiseResolvers<Value>

Viewport

useRenderer

createRenderer

RenderOptions

isCancelError

Design philosophy

Flow control is not screen state

Components remain normal components

The caller owns the next step

Cancellation is lifecycle, not an afterthought

Comparison

Flow Render and React state

Flow Render and state machines

Why is this not built into React?

Best practices

Keep flows close to the initiating action

Return useful, small values

Make normal cancellation a value when possible

Keep the component responsible for accessibility

Put Viewport under the right providers

Do not await from render

Handle local renderer cancellation

Advanced usage

Preserve an exit animation

Wrap a component-library dialog

Create a domain-specific UI service

Compose flows with ordinary async functions

Isolate a subsystem

Common mistakes

Calling the default renderer without mounting its viewport

Treating every UI change as a flow

Hiding important errors

Letting a component perform every next step

Using exitDelay as an async wait

FAQ

Does Flow Render replace React state?

Does Flow Render replace a state machine?

Can I use my existing dialog component?

Does it work with context and providers?

Mount `Viewport` once

`render`

`PromiseResolvers<Value>`

`Viewport`

`useRenderer`

`createRenderer`

`RenderOptions`

`isCancelError`

Put `Viewport` under the right providers

Using `exitDelay` as an async wait

Is `exitDelay` required for animations?