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

[shixianqin]

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.

Installation

npm i @flow-render/vue

Quick Start

Mount the Viewport

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

<!-- App.vue -->

<script setup lang="ts">
  import { Viewport } from '@flow-render/vue'
</script>

<template>
  <YourApp/>
  <Viewport/> <!-- Dynamic components are rendered here -->
</template>

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.

<!-- ConfirmDialog.vue -->

<script setup lang="ts">
  import { type PromiseResolvers } from '@flow-render/vue'

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

  let props = defineProps<Props>()
</script>

<template>
  <dialog open>
    <div>{{title}}</div>
    <div>
      <button @click="props.resolve(true)">Yes</button>
      <button @click="props.resolve(false)">No</button>
      <button @click="props.reject(new Error('Cancel'))">Cancel</button>
    </div>
  </dialog>
</template>

Callbacks are automatically injected when rendering:

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

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.

<!-- ConfirmDialog.vue -->

<script setup lang="ts">
  interface Props {
    title: string
    onYes: () => void
    onNo: () => void
    onCancel: () => void
  }

  const props = defineProps<Props>()
</script>

<template>
  <dialog open>
    <div>{{props.title}}</div>
    <div>
      <button @click="props.onYes">Yes</button>
      <button @click="props.onNo">No</button>
      <button @click="props.onCancel">Cancel</button>
    </div>
  </dialog>
</template>

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

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

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

---

children prop

Vue has a special children prop that is automatically mapped to the slots.
When your component needs to receive children, exclude the children prop from Props, use <slot/> in the
template.

<!-- ConfirmDialog.vue -->

<script setup lang="ts">
  import { type PromiseResolvers } from '@flow-render/vue'

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

  // Exclude 'children' from defineProps
  const props = defineProps<Props>()
</script>

<template>
  <dialog open>
    <div>{{ props.title }}</div>
    <!-- Render children via default slot -->
    <slot/>
    <button @click="props.resolve(true)">Yes</button>
  </dialog>
</template>

Pass children when rendering:

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

const result = await render(ConfirmDialog, {
  title: 'Confirm',
  children: 'Are you sure you want to continue?'
})

---

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:

1. Dynamically render on demand
2. Display UI and wait for user operations
3. 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

[aniruddhaadak80]

Hey @shixianqin,

Working with Vue reactivity system and compilers can sometimes present interesting edge cases. A few quick things to consider regarding this topic:

1. Reactivity & Refs: Remember that reactive() unwraps refs automatically, but accessing private properties of proxy classes inherently breaks proxy traps. Always interact with the standard exposed endpoints.
2. Component Lifecycle & state: If you are mixing <script setup>, ensure you aren???t trying to mutate props directly or losing reactivity when destructuring (use toRefs if needed).

I highly recommend checking out the Vue DevTools extension to inspect the component tree and verify if the state is updating as expected. Let me know if you want to dig deeper into the specific component logic.

Hope this points you in the right direction! Let me know how it goes. Happy coding!

[selcukcukur]

@shixianqin That’s a very interesting approach — thanks for sharing Flow Render.

What stands out is how it flips the usual state‑driven pattern into a Promise‑based flow. Instead of juggling flags and watchers, you can literally await a dialog or form component and continue your logic once the user has interacted. That makes multi‑step UI flows (confirm → fill form → submit) read like linear code, which is much easier to reason about and maintain.

A few highlights I see from your examples:

• Viewport mount: central place where dynamic components appear, so you don’t have to wire up modal containers everywhere.
• Executor mode: feels natural for new components, since you just call resolve/reject directly.
• Adapter mode: powerful for retrofitting existing components or adding conditional logic without rewriting them.
• Children/slots handling: nice touch to keep Vue’s slot semantics intact.
• Use cases: confirmation dialogs, permission checks, guided workflows — all the places where async/await reads better than scattered state.

For teams already using Vue/Nuxt, this could simplify a lot of boilerplate around modals and step‑based flows. Instead of managing global state or event buses, you just await render(...) and continue.

I’d be curious to see how this integrates with Nuxt’s server routes or Vuex/Pinia stores — for example, intercepting a login flow or permission check before dispatching an action. But even as‑is, it looks like a clean abstraction for interactive UI logic.

Nice work — this feels like it could become a standard pattern for handling dialogs and workflows in Vue projects.