The @beeq/vue package provides Vue 3 component wrappers around every BEEQ web component. Benefits over using the raw Custom Elements directly include:
- TypeScript prop checking
v-model support for form controls- Integration with Vue Router links
- Idiomatic
@bq* event handler syntax
Installation
Install the packages
npm install @beeq/{core,vue}
@beeq/core is a peer dependency of @beeq/vue. Both packages must be installed.
Configure Vite and copy SVG assets
Tell Vue’s template compiler to treat all bq-* tags as custom elements, and copy the icon SVG assets to your output directory:import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import vueJsx from '@vitejs/plugin-vue-jsx';
import { viteStaticCopy } from 'vite-plugin-static-copy';
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
// Treat all bq- tags as custom elements
isCustomElement: (tag) => tag.includes('bq-'),
},
},
}),
vueJsx(),
viteStaticCopy({
targets: [
{
src: './node_modules/@beeq/core/dist/beeq/svg/*',
dest: 'assets/svg',
},
],
}),
],
});
Import styles and set the icon base path
Import the BEEQ global stylesheet and call setBasePath in your application entry file:import { createApp } from 'vue';
import { setBasePath } from '@beeq/core';
import '@beeq/core/dist/beeq/beeq.css';
import App from './App.vue';
setBasePath('icons/svg');
createApp(App).mount('#app');
You can also point setBasePath at a CDN to skip the asset-copy step entirely:import { setBasePath } from '@beeq/core';
setBasePath('https://cdn.jsdelivr.net/npm/[email protected]/24/outline');
Usage
v-model binding
BEEQ form components support v-model for two-way data binding:
<script setup lang="ts">
import { ref } from 'vue';
const name = ref('John Doe');
</script>
<template>
<h1>Hello {{ name }}</h1>
<bq-input
name="name"
placeholder="Please type your name..."
v-model="name"
@bqClear="name = ''"
>
<label slot="label">Your name</label>
<bq-icon name="user" slot="prefix"></bq-icon>
</bq-input>
</template>
Event handlers
BEEQ custom events are exposed with the @bq* prefix in Vue templates. The example above uses @bqClear to reset the input value when the user clicks the clear button.
All BEEQ events follow the same naming convention: the bq prefix plus the event name in camelCase (e.g. @bqChange, @bqClick, @bqFocus, @bqBlur).
Importing from @beeq/vue
You can also import components explicitly from @beeq/vue for better tree-shaking:
<script setup lang="ts">
import { BqButton, BqInput } from '@beeq/vue';
import { ref } from 'vue';
const email = ref('');
const handleChange = (ev: CustomEvent<{ value: string }>) => {
email.value = ev.detail.value;
};
</script>
<template>
<BqInput
name="email"
type="email"
:value="email"
@bqChange="handleChange"
>
<label slot="label">Email address</label>
</BqInput>
<BqButton appearance="primary">Subscribe</BqButton>
</template>
When using a different icons library via CDN, make sure the icon names you pass to <bq-icon name="..."> match the filenames provided by that library.