How to use Aqua in Vue

Aqua DS integrates seamlessly with Vue 3, leveraging native features such as v-bind, v-model, and event shorthands like @click (or v-on:click). To get started, you simply need to:

Install the Vue package from NPM (@aqua-ds/vue).
Have a Vue 3 project initialized and ready.
Apply minimal setup configurations to register and use Aqua DS components in your application.

This ensures that Aqua DS behaves like any other Vue-native component, making it straightforward to adopt within your existing project.

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 vue from '@vitejs/plugin-vue'
...

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

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.

You should import each component explicitly inside your Vue file and register it in the components option of defineComponent.

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({  // Register them inside the defineComponent({ components: { ... } })
	components: {
    AqButton,
  },
  setup() {
	  const handleclick = (e: Event) => {
	    console.log('AqButton click from vue ', e);
	  };
	}
	return {
		handleclick,
	}
});
</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>

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> ⚠️

</aside>