AquaDS Vue3

✨ Design together. Build together. Speak the same language. ✨

npm i @aqua-ds/vue

Works smoothly with Vue 3 using on-demand imports and Vite configuration.

Installation

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

1. Ensure you have a Vue 3 project initialized and are using the latest versions of Node.js and NPM.

2. Install Aqua DS Package for Vue:

   npm i @aqua-ds/vue

3. Configure vite.config.js:

4. 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>

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

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>

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

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).

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).

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)

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.

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.

For example, when a developer uses the v-slot or #slot syntax on a Vue component, Vue expects to find a Vue-native slot. However, since the slot is defined using the Web Component specification (as per-Stencil), Vue is not aware of it.

To properly use our slots, developers must use the native Web Component slot syntax provided by the Stencil API—that is, using the slot attribute directly in the markup.

 <aq-dropdown id="dropdown-1" :items="items" :popover-width="300">
  <aq-button slot="activator" is-outline
    ><i class="aq-icon-three-dots-vertical"></i
  ></aq-button>
</aq-dropdown>

When you do this, you'll gain access to the Web Component slot and be able to use it as needed.

If you're using Vetur, a linter, or any tool with strict Vue file validation, and it shows a syntax error, follow these steps:

“slot” attributes are deprecated

Don’t worry about that error — it’s not caused by your code, nor is it related to our library. It’s just that Vue mistakenly thinks we’re using the Vue 2 API, but in reality, we’re targeting the Stencil API. To prevent and fix this warning, you just need to configure it properly in your eslint.config file:

// eslint.config.ts
rules: {
  // ...
  'vue/no-deprecated-slot-attribute': 'off',
  // ...
}

Vue Component Naming Convention

In Aqua DS, all Vue components must be used in lowercase (e.g., aq-button) when declared in your templates. This is required to ensure maximum compatibility across platforms, especially when using components in HTML-like syntaxes where uppercase tags are not recognized properly.

Even though you import the component in PascalCase in your JavaScript (AqButton), it should always be used in lowercase in your Vue templates:

<template>
  <aq-button variant="primary">Button</aq-button> <!-- ✅ Correct -->
</template>

Avoid using <AqButton> in templates. It may not render correctly in some environments.

Important Notes

Component Names:

Aqua DS components must be used in kebab-case (aq-button, not AqButton) to ensure full compatibility in Vue templates.

Tree Shaking:

To reduce your final bundle size, only import the components you use.

Example (in your main file or component script):

<script>
...
import {
  AqDropdown,
  AqButton,
  AqSubheading,
  AqCheckbox,
  AqBadge,
} from '@aqua-ds/vue'
...
</script>

✨ Design together. Build together. Speak the same language. ✨