Aqua Basis

Directives in Aqua DS are implemented through a custom system based on the DOM MutationObserver API, allowing us to replicate the behavior of directives commonly seen in frameworks. This system observes changes in the DOM and applies specific behaviors automatically, ensuring reactive and declarative enhancements without requiring additional boilerplate code.

They allow developers to extend the HTML syntax with additional capabilities, such as showing tooltips, handling click triggers, or modify some element of the DOM manually.

Instead of writing JavaScript logic for each component individually, directives encapsulate that logic in a reusable and consistent way.

How it Works in Aqua DS

Our system uses MutationObserver to detect when an element with a directive is added or updated in the DOM.
Once detected, the directive’s behavior is applied (e.g., attaching event listeners, styling, or functional logic).
This ensures a lightweight and framework-agnostic approach, keeping our directives consistent across different environments (Stencil, Vue, React, Angular, or plain Web Components).
All the directives should included in the code as attributes with aq- syntax.

Consideration

We use an enum to enable an autocomplete feature at the moment of implement the directives. You can use it importing our Directives Enum.

// Example Vue
// main.ts
import { Directives } from "@aqua-ds/web-components/enums";

app.use(LibraryDirectives, {
  directives: [Directives.DIALOG, Directives.DRAWER, Directives.TOOLTIP, Directives.SPINNER],
})

Implementation in Frameworks

The flexibility makes directives framework-agnostic while keeping the developer experience familiar and loading this directives on-load demanding. therefore, the directives can be easily integrated depending on the framework.

Web Components

Via npm

import { setupDirectives } from '@aqua-ds/web-components/directives';

setupDirectives(['aq-spinner', 'aq-dialog', 'aq-drawer', 'aq-tooltip'])

Via Script

<aside> ℹ️

We are working on this feature.

</aside>

Vue 3


// main.ts
import { LibraryDirectives } from '@aqua-ds/vue/lib/plugin.ts'

app.use(LibraryDirectives, {
  directives: ['aq-spinner', 'aq-dialog', 'aq-drawer', 'aq-tooltip'],
})

React

// main.ts
import { LibraryDirectives } from '@aqua-ds/react/lib/index.js';

LibraryDirectives(['aq-dialog', 'aq-tooltip', 'aq-spinner', 'aq-drawer']);

Angular

// main.ts
import { LibraryDirectives } from '@aqua-ds/angular';

LibraryDirectives(['aq-dialog', 'aq-spinner', 'aq-drawer', 'aq-tooltip']);

Aqua DS Directives

Tooltip

Provides contextual information when hovering over or focusing on an element.

Tooltip

Dialog

Displays a modal dialog by targeting a component’s ID.

Dialog

Drawer

Enables the display of a side panel (drawer) by binding the directive to a component’s ID.

Drawer

Spinner

Toggles a loading spinner overlay on a component.

Spinner

On this page

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

back Aqua.png