Installation

To install Aqua DS in a Vue 3 project using NPM:

Ensure you have a Vue 3 project initialized and are using the latest versions of Node.js and NPM.
Install Aqua DS Package for Vue:
```
npm i @aqua-ds/vue
```
Configure vite.config.js:

If using Vite, you must add the following so Vue knows which tags should be treated as Web Components instead of Vue components during the template compilation process (Learn more at Vue and Web Components | Vue.js):

...
import vueJsx from '@vitejs/plugin-vue-jsx'
...

export default defineConfig({
	...
  plugins: [
		vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('aq-'),
        },
      },
    }),
    vueJsx(),
    ...
    ]
  }
);

Using Aqua DS Components in Vue 3

Once you’ve installed Aqua DS and set up your project, you can begin using components in your Vue 3 templates.

Here’s how you can use components from the official list:

Components

Example: <aq-button>

<!-- anyFile.vue -->
<script lang="ts">
import { defineComponent } from 'vue';
import { AqButton } from '@aqua-ds/vue';

export default defineComponent({
	components: {
    AqButton,
  },
  setup() {
	  const handleclick = (e: Event) => {
	    console.log('AqButton click from vue ', e);
	  };
	}
});
</script>

<template>
  <div class="container">
    <aq-button @click="handleclick" variant="primary" type="submit">
      <em class="aq-icon-settings"></em> Button
    </aq-button>
	</div>
</template>

<aside> 💡

Tip: Aqua DS supports tree-shaking, so importing only the components you use keeps your final bundle small.

</aside>

Importing Components in Vue

To ensure full compatibility when using Aqua components in Vue.js, always import them explicitly inside a defineComponent block.

<script lang="ts">
import { AqBadge } from '@aqua-ds/vue';
import { defineComponent } from 'vue';

export default defineComponent({
  components: {
    AqBadge,
  },
});
</script>

<template>
	...
  <aq-badge state="warning">Warning</aq-badge>
	...
</template>

Handling Component Events

Aqua DS components emit custom DOM events that are fully compatible with Vue 3’s native event handling syntax. This means you can use v-on: or the shorthand @ to listen for events, just like with any standard Vue component.

Example: Listening to an Event

<script lang="ts">
import { AqButton } from '@aqua-ds/vue';
import { defineComponent } from 'vue';

export default defineComponent({
  components: { AqButton },
  setup() {
    const handleClick= (ev: Event) => {
      console.log('Handling button click event: ', ev);
    };
    return { 
		  handleClick
    };
  }
});
</script>
<template>
	<div>
	  <aq-button variant="primary" @click="handleClick">
	    Click Me
	  </aq-button>
  </div>
</template>

<script lang="ts">
import { AqCheckbox } from '@aqua-ds/vue';
import { defineComponent } from 'vue';

export default defineComponent({
  components: { AqCheckbox },
  setup() {
    const handleValueChanged = (ev: Event) => {
      console.log('Handling checkbox custom aqChange from vue: ', ev);
    };
    return { 
		  handleValueChanged
    };
  }
});
</script>

<template>
	<div>
		<aq-checkbox 
			id-checkbox="checkbox-2" 
			name="checkbox-2" 
			label="This is a checkbox 2" 
			icon="aq-icon-message"
      is-required 
      info="This is an information tooltip" 
      value-checkbox="option-2" 
      @input="handleValueChanged"
    >
    </aq-checkbox>
	</div>
</template>

Two-Way Binding

Aqua DS is compatible with Vue 3’s v-model for two-way binding, allowing your application to stay in sync with component values.

Example Using v-model

<script lang="ts">
import { AqCheckbox } from '@aqua-ds/vue';
import { defineComponent } from 'vue';

export default defineComponent({
  components: { AqCheckbox },
  setup() {
	  const selectedValue = ref();
	  return {
		  selectedValue,
	  }
  }
});
</script>
<template>
	<div>
		<aq-checkbox 
			id-checkbox="checkbox-2" 
			name="checkbox-2" 
			label="This is a checkbox 2" 
			icon="aq-icon-message"
      is-required 
      info="This is an information tooltip" 
      value-checkbox="option-2" 
      @input="handleValueChanged"
      v-model="selectedValue"
    >
    </aq-checkbox>
	</div>
</template>

<aside> 💡

Always refer to the documentation of each individual component for a complete list of supported events, their purpose, and usage examples.

</aside>

<aside> ℹ️

Only some Aqua DS components are compatible with v-model, particularly those that deal with user input and require reactive state handling (such as form fields).

</aside>

Passing Properties to Components

When using Aqua DS components in Vue 3, you can pass properties just like you would with any other component. Aqua DS supports standard HTML attributes, as well as custom component-specific props. Vue automatically converts kebab-case attributes into camelCase props internally.

<script lang="ts">
import { AqButtonSplit } from '@aqua-ds/vue';
import { defineComponent, ref } from 'vue';
	
export default defineComponent({
  components: { AqButtonSplit },
  setup() {
    const handleaqclickLeft = (e: Event) => {
      console.log('Handling button-group custom aqclick from vue ', e);
    };
    const handleaqclickRight = (e: Event) => {
      console.log('Handling button-group custom aqclick from vue ', e);
    };
    const handleaqclickItem = (e: Event) => {
      console.log('Handling button-group custom aqclick from vue ', e);
    };
    const items = ref([{
	    id: "id1",
	    name: "option1"
	  },
	  {
	    id: "id2",
	    name: "option2"
	  }]);

    return {
      handleaqclickLeft,
      handleaqclickRight,
      handleaqclickItem,
      items
    };
  },
});
</script>

<template>
	<div class="section">
	  <aq-button-split
		  :items="items"
		  variant="success"
		  size="medium"
		  icon="aq-icon-send-money"
		  @clickLeft="handleAqClickLeft"
		  @clickRight="handleAqClickRight"
		  @clickItem="handleAqClickItem"
	  >
		  Button
	  </aq-button-split>
  </div>
</template>

This is a practical example of using the <aq-button-split> component in Vue 3. This includes:

Static props like variant, size, and icon.
Dynamic props passed via v-bind (shorthand :).
Event bindings using Vue's @ directive (v-on shorthand).

<aside> ⚠️

All Aqua DS component events are fully compatible with Vue 3’s native event binding syntax. You can listen to any custom event emitted by a component using either:

v-on:eventName
@eventName (shorthand for v-on) </aside>

<aside> ℹ️

Most Aqua DS component props are fully compatible with Vue’s v-bind directive, allowing you to dynamically bind data to the component’s attributes.

</aside>

Implementing custom Slots

When we develop a component using the Stencil API, the slot element is implemented based on Web Component standards. This differs from bindings and custom events, which are adapted to work with framework-specific integrations.

When the component is transpiled into a Vue component, it is not a fully native Vue component but rather a wrapper around a Web Component. As a result, some Vue-specific features are not fully supported.