Aqua Basis

npm i @aqua-ds/web-components

Use the components directly in HTML without any framework by installing the Aqua Web Components package.

Installation

Aqua DS Web Components can be installed in two different ways depending on your project’s needs:

Using NPM

For projects using Node.js with a build system (like Vite, Webpack, etc.):

Make sure your project is initialized and supports modern JavaScript.
Install Aqua DS Web Components:

npm i @aqua-ds/web-components

Import and define the components in your JavaScript entry point:

<aside> ℹ️

When use defineCustomElements you will subscribe all the web-components on the website. That will enable the possibility of access to any web-component at any moment. That not affects the app performance.

</aside>

import { defineCustomElements } from '@aqua-ds/web-components/loader';
defineCustomElements();

Using CDN

For simpler setups (e.g., pure HTML without a build step):

Include the Aqua DS script in your HTML:

<script type="module" src=[url-to-cdn]></script>

<aside> ⚠️

If you need access to the URL AQUA CDN to connect to Aqua’s private cdn, please send an email to the FrontOps team [email protected]

</aside>

<aside> 💡

Note: CDN is ideal for prototyping or static environments.

</aside>

Using Components

Aqua DS offers a wide range of Web Components that can be used across compatible environments. Each component comes with defined props, slots, and events to provide flexible UI behavior.

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

Components

Example: <aq-button>

<aq-button variant="primary" type="submit">
  <em class="aq-icon-settings"></em>Submit
</aq-button>

Handling Events

Aqua DS components emit custom events to allow interaction and dynamic behavior in your applications. When using Web Components directly (e.g., in HTML or JavaScript), you can listen to these events using standard DOM event listeners.

<aq-button variant="primary" type="submit" id="aqButton">
  <em class="aq-icon-settings"></em>Submit
</aq-button>

<script>
	const aqButton = document.getElementById("aqButton");
	
	aqButton.addEventListener('click', (event)=> {
		console.log("Click from AqButton: ", event.detail);
	});
</script>

Each Aqua DS component defines its own set of custom events to support interactive and reactive behavior. These events are designed to reflect meaningful user interactions or internal state changes.

<aside> ℹ️

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

</aside>

Using the correct event names and handlers ensures proper integration within your app logic and facilitates a seamless user experience.

Passing Properties to Web Components

In Aqua DS, you can pass properties (also known as "props" or "attributes") directly to Web Components via HTML attributes or JavaScript.

These properties control the component’s behavior, appearance, and logic. Each component has its own set of supported props, which you can find in its documentation.

HTML Example

<aq-text-field
	id="aqTextField"  
	type="number"
	placeholder="This has slot with left content" 
	icon="aq-icon-settings" 
	label="This is a label" 
	sublabel="Sub"
  helper-text="This is a helper text"
  info="This is a tooltip"
  char-counter
	is-required
	is-textarea>
</aq-text-field>

Javascript Example

const aqTextField = document.getElementById("aqTextField");
aqTextField.icon = "aq-icon-email";
aqTextField.label = "TextField Label"

Boolean props (like is-disabled or is-required) can be added without a value in HTML.

Complex data types as property

In WebComponents some props only works when are manually set via Javascript, depending on the component’s internal logic.

<aq-button-split
    id="aqButtonSplit"
    type="button"
    variant="default"
    size="medium"
    info="This is a tooltip" >
    <em class="aq-icon-send-money"></em> Button
</aq-button-split>
<script>
  const buttonSplit = document.querySelector('#aqButtonSplit');
  
  // Setting a JS-only attribute (complex object)
  buttonSplit.items = [
    { id: "1", name: "Option 1" },
    { id: "2", name: "Option 2" },
    { id: "3", name: "Option 3" }
  ];
</script>

<aside> ℹ️

</aside>