1---
2category: Component
3outline: deep
4---
5 
6# createTemplatePromise
7 
8Template as Promise. Useful for constructing custom Dialogs, Modals, Toasts, etc.
9 
10## Usage
11 
12```vue
13<script setup lang="ts">
14import { createTemplatePromise } from '@vueuse/core'
15 
16const TemplatePromise = createTemplatePromise<ReturnType>()
17 
18async function open() {
19  const result = await TemplatePromise.start()
20  // button is clicked, result is 'ok'
21}
22</script>
23 
24<template>
25  <TemplatePromise v-slot="{ promise, resolve, reject, args }">
26    <!-- your UI -->
27    <button @click="resolve('ok')">
28      OK
29    </button>
30  </TemplatePromise>
31</template>
32```
33 
34## Features
35 
36- **Programmatic** - call your UI as a promise
37- **Template** - use Vue template to render, not a new DSL
38- **TypeScript** - full type safety via generic type
39- **Renderless** - you take full control of the UI
40- **Transition** - use support Vue transition
41 
42This function is migrated from [vue-template-promise](https://github.com/antfu/vue-template-promise)
43 
44## Usage
45 
46`createTemplatePromise` returns a **Vue Component** that you can directly use in your template with `<script setup>`
47 
48```ts twoslash include main
49import { createTemplatePromise } from '@vueuse/core'
50 
51const TemplatePromise = createTemplatePromise()
52const MyPromise = createTemplatePromise<boolean>() // with generic type
53```
54 
55In template, use `v-slot` to access the promise and resolve functions.
56 
57```vue
58<template>
59  <TemplatePromise v-slot="{ promise, resolve, reject, args }">
60    <!-- you can have anything -->
61    <button @click="resolve('ok')">
62      OK
63    </button>
64  </TemplatePromise>
65  <MyPromise v-slot="{ promise, resolve, reject, args }">
66    <!-- another one -->
67  </MyPromise>
68</template>
69```
70 
71The slot will not be rendered initially (similar to `v-if="false"`), until you call the `start` method from the component.
72 
73```ts
74// @include: main
75// ---cut---
76const result = await TemplatePromise.start()
77```
78 
79Once `resolve` or `reject` is called in the template, the promise will be resolved or rejected, returning the value you passed in. Once resolved, the slot will be removed automatically.
80 
81### Passing Arguments
82 
83You can pass arguments to the `start` with arguments.
84 
85```ts twoslash include passing-arguments
86import { createTemplatePromise } from '@vueuse/core'
87 
88const TemplatePromise = createTemplatePromise<boolean, [string, number]>()
89```
90 
91```ts
92// @include: passing-arguments
93// ---cut---
94const result = await TemplatePromise.start('hello', 123) // Pr
95```
96 
97And in the template slot, you can access the arguments via `args` property.
98 
99```vue
100<template>
101  <TemplatePromise v-slot="{ args, resolve }">
102    <div>{{ args[0] }}</div>
103    <!-- hello -->
104    <div>{{ args[1] }}</div>
105    <!-- 123 -->
106    <button @click="resolve(true)">
107      OK
108    </button>
109  </TemplatePromise>
110</template>
111```
112 
113### Singleton Mode
114 
115Use the `singleton` option to ensure only one instance of the promise can be active at a time. If `start` is called while a promise is already active, it will return the existing promise instead of creating a new one.
116 
117```ts
118import { createTemplatePromise } from '@vueuse/core'
119 
120const TemplatePromise = createTemplatePromise<boolean>({
121  singleton: true,
122})
123 
124// These will return the same promise if called in quick succession
125const result1 = TemplatePromise.start()
126const result2 = TemplatePromise.start() // returns the same promise as result1
127```
128 
129### Transition
130 
131You can use transition to animate the slot.
132 
133```vue
134<script setup lang="ts">
135const TemplatePromise = createTemplatePromise<ReturnType>({
136  transition: {
137    name: 'fade',
138    appear: true,
139  },
140})
141</script>
142 
143<template>
144  <TemplatePromise v-slot="{ resolve }">
145    <!-- your UI -->
146    <button @click="resolve('ok')">
147      OK
148    </button>
149  </TemplatePromise>
150</template>
151 
152<style scoped>
153.fade-enter-active,
154.fade-leave-active {
155  transition: opacity 0.5s;
156}
157.fade-enter,
158.fade-leave-to {
159  opacity: 0;
160}
161</style>
162```
163 
164Learn more about [Vue Transition](https://vuejs.org/guide/built-ins/transition.html).
165 
166### Slot Props
167 
168The slot provides the following props:
169 
170| Prop          | Type                                     | Description                                               |
171| ------------- | ---------------------------------------- | --------------------------------------------------------- |
172| `promise`     | `Promise<Return> \| undefined`           | The current promise instance                              |
173| `resolve`     | `(v: Return \| Promise<Return>) => void` | Resolve the promise with a value                          |
174| `reject`      | `(v: any) => void`                       | Reject the promise                                        |
175| `args`        | `Args`                                   | Arguments passed to `start()`                             |
176| `isResolving` | `boolean`                                | `true` when resolving another promise passed to `resolve` |
177| `key`         | `number`                                 | Unique key for list rendering                             |
178 
179```vue
180<template>
181  <TemplatePromise v-slot="{ promise, resolve, reject, args, isResolving }">
182    <div v-if="isResolving">
183      Loading...
184    </div>
185    <div v-else>
186      <button @click="resolve('ok')">
187        OK
188      </button>
189      <button @click="reject('cancelled')">
190        Cancel
191      </button>
192    </div>
193  </TemplatePromise>
194</template>
195```
196 
197## Motivation
198 
199The common approach to call a dialog or a modal programmatically would be like this:
200 
201```ts
202const dialog = useDialog()
203const result = await dialog.open({
204  title: 'Hello',
205  content: 'World',
206})
207```
208 
209This would work by sending these information to the top-level component and let it render the dialog. However, it limits the flexibility you could express in the UI. For example, you could want the title to be red, or have extra buttons, etc. You would end up with a lot of options like:
210 
211```ts
212const result = await dialog.open({
213  title: 'Hello',
214  titleClass: 'text-red',
215  content: 'World',
216  contentClass: 'text-blue text-sm',
217  buttons: [
218    { text: 'OK', class: 'bg-red', onClick: () => {} },
219    { text: 'Cancel', class: 'bg-blue', onClick: () => {} },
220  ],
221  // ...
222})
223```
224 
225Even this is not flexible enough. If you want more, you might end up with manual render function.
226 
227```ts
228const result = await dialog.open({
229  title: 'Hello',
230  contentSlot: () => h(MyComponent, { content }),
231})
232```
233 
234This is like reinventing a new DSL in the script to express the UI template.
235 
236So this function allows **expressing the UI in templates instead of scripts**, where it is supposed to be, while still being able to be manipulated programmatically.
237 
238## Type Declarations
239 
240```ts
241export interface TemplatePromiseProps<Return, Args extends any[] = []> {
242  /**
243   * The promise instance.
244   */
245  promise: Promise<Return> | undefined
246  /**
247   * Resolve the promise.
248   */
249  resolve: (v: Return | Promise<Return>) => void
250  /**
251   * Reject the promise.
252   */
253  reject: (v: any) => void
254  /**
255   * Arguments passed to TemplatePromise.start()
256   */
257  args: Args
258  /**
259   * Indicates if the promise is resolving.
260   * When passing another promise to `resolve`, this will be set to `true` until the promise is resolved.
261   */
262  isResolving: boolean
263  /**
264   * Options passed to createTemplatePromise()
265   */
266  options: TemplatePromiseOptions
267  /**
268   * Unique key for list rendering.
269   */
270  key: number
271}
272export interface TemplatePromiseOptions {
273  /**
274   * Determines if the promise can be called only once at a time.
275   *
276   * @default false
277   */
278  singleton?: boolean
279  /**
280   * Transition props for the promise.
281   */
282  transition?: TransitionGroupProps
283}
284export type TemplatePromise<
285  Return,
286  Args extends any[] = [],
287> = DefineComponent<object> & {
288  new (): {
289    $slots: {
290      default: (_: TemplatePromiseProps<Return, Args>) => any
291    }
292  }
293} & {
294  start: (...args: Args) => Promise<Return>
295}
296/**
297 * Creates a template promise component.
298 *
299 * @see https://vueuse.org/createTemplatePromise
300 *
301 * @__NO_SIDE_EFFECTS__
302 */
303export declare function createTemplatePromise<Return, Args extends any[] = []>(
304  options?: TemplatePromiseOptions,
305): TemplatePromise<Return, Args>
306```
307