Custom Components

One of the primary features of this module is the ability to automatically register a subset of your project's Vue components as custom components in Builder. This allows you to use your own components in Builder content.

By default, this module will automatically register all .vue components in your project's builder/components directory. See the Configuration section for more information.

Getting started

First, create the builder/components directory (or whatever you configured the directory to be) in the root of your project:

mkdir -p builder/components

Next, create a new Vue component in the builder/components directory. In this example, we'll be creating a Hero component:

<!-- builder/components/Hero.vue -->
<template>
  <div>
    Hello, {{ text }}!
  </div>
</template>

<script setup lang="ts">
defineProps<{
  text: string
}>()

defineBuilderComponent({
  friendlyName: 'Hero',
  description: 'Test description',
  inputs: [{
    name: 'text',
    type: 'string',
    defaultValue: 'world'
  }]
})
</script>

Notice the defineBuilderComponent helper at the bottom of the file. This is a compile-time macro which is used to register the component with Builder. It accepts a single argument, which is an object. See the type declaration or the Builder docs for more information.

This component defines one input, text, which is of type string with a default value of world. This directly corresponds with the component's text prop.

Using custom components

If you use the <BuilderContent> component provided by this module, your components will be registered with Builder automatically.

If you don't want to or can't use this component, you can access your project's Builder components by using the useBuilderComponents composable anywhere in your project:

<template>
  <!-- Use the <BuilderContent> component provided by this module instead if possible! -->
  <Content
    :custom-components="customComponents"
    ...
  />
</template>
<script setup lang="ts">
import { Content } from '@builder.io/sdk-vue/vue3'

const customComponents = useBuilderComponents()
</script>