1---
2category: Component
3outline: deep
4---
5 
6# createReusableTemplate
7 
8Define and reuse template inside the component scope.
9 
10## Motivation
11 
12It's common to have the need to reuse some part of the template. For example:
13 
14```vue
15<template>
16  <dialog v-if="showInDialog">
17    <!-- something complex -->
18  </dialog>
19  <div v-else>
20    <!-- something complex -->
21  </div>
22</template>
23```
24 
25We'd like to reuse our code as much as possible. So normally we might need to extract those duplicated parts into a component. However, in a separated component you lose the ability to access the local bindings. Defining props and emits for them can be tedious sometimes.
26 
27So this function is made to provide a way for defining and reusing templates inside the component scope.
28 
29## Usage
30 
31In the previous example, we could refactor it to:
32 
33```vue
34<script setup lang="ts">
35import { createReusableTemplate } from '@vueuse/core'
36 
37const [DefineTemplate, ReuseTemplate] = createReusableTemplate()
38</script>
39 
40<template>
41  <DefineTemplate>
42    <!-- something complex -->
43  </DefineTemplate>
44 
45  <dialog v-if="showInDialog">
46    <ReuseTemplate />
47  </dialog>
48  <div v-else>
49    <ReuseTemplate />
50  </div>
51</template>
52```
53 
54- `<DefineTemplate>` will register the template and renders nothing.
55- `<ReuseTemplate>` will render the template provided by `<DefineTemplate>`.
56- `<DefineTemplate>` must be used before `<ReuseTemplate>`.
57 
58> **Note**: It's recommended to extract as separate components whenever possible. Abusing this function might lead to bad practices for your codebase.
59 
60### Options API
61 
62When using with [Options API](https://vuejs.org/guide/introduction.html#api-styles), you will need to define `createReusableTemplate` outside of the component setup and pass to the `components` option in order to use them in the template.
63 
64```vue
65<script>
66import { createReusableTemplate } from '@vueuse/core'
67import { defineComponent } from 'vue'
68 
69const [DefineTemplate, ReuseTemplate] = createReusableTemplate()
70 
71export default defineComponent({
72  components: {
73    DefineTemplate,
74    ReuseTemplate,
75  },
76  setup() {
77    // ...
78  },
79})
80</script>
81 
82<template>
83  <DefineTemplate v-slot="{ data, msg, anything }">
84    <div>{{ data }} passed from usage</div>
85  </DefineTemplate>
86 
87  <ReuseTemplate :data="data" msg="The first usage" />
88</template>
89```
90 
91### Passing Data
92 
93You can also pass data to the template using slots:
94 
95- Use `v-slot="..."` to access the data on `<DefineTemplate>`
96- Directly bind the data on `<ReuseTemplate>` to pass them to the template
97 
98```vue
99<script setup lang="ts">
100import { createReusableTemplate } from '@vueuse/core'
101 
102const [DefineTemplate, ReuseTemplate] = createReusableTemplate()
103</script>
104 
105<template>
106  <DefineTemplate v-slot="{ data, msg, anything }">
107    <div>{{ data }} passed from usage</div>
108  </DefineTemplate>
109 
110  <ReuseTemplate :data="data" msg="The first usage" />
111  <ReuseTemplate :data="anotherData" msg="The second usage" />
112  <ReuseTemplate v-bind="{ data: something, msg: 'The third' }" />
113</template>
114```
115 
116### TypeScript Support
117 
118`createReusableTemplate` accepts a generic type to provide type support for the data passed to the template:
119 
120```vue
121<script setup lang="ts">
122import { createReusableTemplate } from '@vueuse/core'
123 
124// Comes with pair of `DefineTemplate` and `ReuseTemplate`
125const [DefineFoo, ReuseFoo] = createReusableTemplate<{ msg: string }>()
126 
127// You can create multiple reusable templates
128const [DefineBar, ReuseBar] = createReusableTemplate<{ items: string[] }>()
129</script>
130 
131<template>
132  <DefineFoo v-slot="{ msg }">
133    <!-- `msg` is typed as `string` -->
134    <div>Hello {{ msg.toUpperCase() }}</div>
135  </DefineFoo>
136 
137  <ReuseFoo msg="World" />
138 
139  <!-- @ts-expect-error Type Error! -->
140  <ReuseFoo :msg="1" />
141</template>
142```
143 
144Optionally, if you are not a fan of array destructuring, the following usages are also legal:
145 
146```vue
147<script setup lang="ts">
148import { createReusableTemplate } from '@vueuse/core'
149 
150const { define: DefineFoo, reuse: ReuseFoo } = createReusableTemplate<{
151  msg: string
152}>()
153</script>
154 
155<template>
156  <DefineFoo v-slot="{ msg }">
157    <div>Hello {{ msg.toUpperCase() }}</div>
158  </DefineFoo>
159 
160  <ReuseFoo msg="World" />
161</template>
162```
163 
164```vue
165<script setup lang="ts">
166import { createReusableTemplate } from '@vueuse/core'
167 
168const TemplateFoo = createReusableTemplate<{ msg: string }>()
169</script>
170 
171<template>
172  <TemplateFoo.define v-slot="{ msg }">
173    <div>Hello {{ msg.toUpperCase() }}</div>
174  </TemplateFoo.define>
175 
176  <TemplateFoo.reuse msg="World" />
177</template>
178```
179 
180::: warning
181Passing boolean props without `v-bind` is not supported. See the [Caveats](#boolean-props) section for more details.
182:::
183 
184### Props and Attributes
185 
186By default, all props and attributes passed to `<ReuseTemplate>` will be passed to the template. If you don't want certain props to be passed to the DOM, you need to define the runtime props:
187 
188```ts
189import { createReusableTemplate } from '@vueuse/core'
190 
191const [DefineTemplate, ReuseTemplate] = createReusableTemplate({
192  props: {
193    msg: String,
194    enable: Boolean,
195  }
196})
197```
198 
199If you don't want to pass any props to the template, you can pass the `inheritAttrs` option:
200 
201```ts
202import { createReusableTemplate } from '@vueuse/core'
203 
204const [DefineTemplate, ReuseTemplate] = createReusableTemplate({
205  inheritAttrs: false,
206})
207```
208 
209### Passing Slots
210 
211It's also possible to pass slots back from `<ReuseTemplate>`. You can access the slots on `<DefineTemplate>` from `$slots`:
212 
213```vue
214<script setup lang="ts">
215import { createReusableTemplate } from '@vueuse/core'
216 
217const [DefineTemplate, ReuseTemplate] = createReusableTemplate()
218</script>
219 
220<template>
221  <DefineTemplate v-slot="{ $slots, otherProp }">
222    <div some-layout>
223      <!-- To render the slot -->
224      <component :is="$slots.default" />
225    </div>
226  </DefineTemplate>
227 
228  <ReuseTemplate>
229    <div>Some content</div>
230  </ReuseTemplate>
231  <ReuseTemplate>
232    <div>Another content</div>
233  </ReuseTemplate>
234</template>
235```
236 
237## Caveats
238 
239### Boolean props
240 
241As opposed to Vue's behavior, props defined as `boolean` that were passed without `v-bind` or absent will be resolved into an empty string or `undefined` respectively:
242 
243```vue
244<script setup lang="ts">
245import { createReusableTemplate } from '@vueuse/core'
246 
247const [DefineTemplate, ReuseTemplate] = createReusableTemplate<{
248  value?: boolean
249}>()
250</script>
251 
252<template>
253  <DefineTemplate v-slot="{ value }">
254    {{ typeof value }}: {{ value }}
255  </DefineTemplate>
256 
257  <ReuseTemplate :value="true" />
258  <!-- boolean: true -->
259 
260  <ReuseTemplate :value="false" />
261  <!-- boolean: false -->
262 
263  <ReuseTemplate value />
264  <!-- string: -->
265 
266  <ReuseTemplate />
267  <!-- undefined: -->
268</template>
269```
270 
271## References
272 
273This function is migrated from [vue-reuse-template](https://github.com/antfu/vue-reuse-template).
274 
275Existing Vue discussions/issues about reusing template:
276 
277- [Discussion on Reusing Templates](https://github.com/vuejs/core/discussions/6898)
278 
279Alternative Approaches:
280 
281- [Vue Macros - `namedTemplate`](https://vue-macros.sxzz.moe/features/named-template.html)
282- [`unplugin-vue-reuse-template`](https://github.com/liulinboyi/unplugin-vue-reuse-template)
283 
284## Type Declarations
285 
286```ts
287type ObjectLiteralWithPotentialObjectLiterals = Record<
288  string,
289  Record<string, any> | undefined
290>
291type GenerateSlotsFromSlotMap<
292  T extends ObjectLiteralWithPotentialObjectLiterals,
293> = {
294  [K in keyof T]: Slot<T[K]>
295}
296export type DefineTemplateComponent<
297  Bindings extends Record<string, any>,
298  MapSlotNameToSlotProps extends ObjectLiteralWithPotentialObjectLiterals,
299> = DefineComponent & {
300  new (): {
301    $slots: {
302      default: (
303        _: Bindings & {
304          $slots: GenerateSlotsFromSlotMap<MapSlotNameToSlotProps>
305        },
306      ) => any
307    }
308  }
309}
310export type ReuseTemplateComponent<
311  Bindings extends Record<string, any>,
312  MapSlotNameToSlotProps extends ObjectLiteralWithPotentialObjectLiterals,
313> = DefineComponent<Bindings> & {
314  new (): {
315    $slots: GenerateSlotsFromSlotMap<MapSlotNameToSlotProps>
316  }
317}
318export type ReusableTemplatePair<
319  Bindings extends Record<string, any>,
320  MapSlotNameToSlotProps extends ObjectLiteralWithPotentialObjectLiterals,
321> = [
322  DefineTemplateComponent<Bindings, MapSlotNameToSlotProps>,
323  ReuseTemplateComponent<Bindings, MapSlotNameToSlotProps>,
324] & {
325  define: DefineTemplateComponent<Bindings, MapSlotNameToSlotProps>
326  reuse: ReuseTemplateComponent<Bindings, MapSlotNameToSlotProps>
327}
328export interface CreateReusableTemplateOptions<
329  Props extends Record<string, any>,
330> {
331  /**
332   * Inherit attrs from reuse component.
333   *
334   * @default true
335   */
336  inheritAttrs?: boolean
337  /**
338   * Props definition for reuse component.
339   */
340  props?: ComponentObjectPropsOptions<Props>
341}
342/**
343 * This function creates `define` and `reuse` components in pair,
344 * It also allow to pass a generic to bind with type.
345 *
346 * @see https://vueuse.org/createReusableTemplate
347 *
348 * @__NO_SIDE_EFFECTS__
349 */
350export declare function createReusableTemplate<
351  Bindings extends Record<string, any>,
352  MapSlotNameToSlotProps extends ObjectLiteralWithPotentialObjectLiterals =
353    Record<"default", undefined>,
354>(
355  options?: CreateReusableTemplateOptions<Bindings>,
356): ReusableTemplatePair<Bindings, MapSlotNameToSlotProps>
357```
358