Installation

To use Aqua DS in a React project, you must have an existing React application running with support for the latest Node and npm versions.

Once your project is ready, you only need to install the package, import the components, and use them directly in JSX.

⚠️ When using Aqua Web Components directly in a React (Next.js) application, they can only be rendered on the client side. This means you must load them inside a Client Component to ensure proper initialization and avoid hydration errors.

We are currently working on a solution to provide better SSR support

Install the React package:

npm i @aqua-ds/react

You’re ready to use Aqua in React!

Using Aqua DS Components

Here's a basic example of how to use an Aqua DS component in a React application:

// App.jsx
import { AqButton } from '@aqua-ds/react';

export const ButtonSet = () => {
	const handleClick = (e: MouseEvent) => {
		console.log('AqButton click from React', e);
	}

  return (
    <div>
      <AqButton variant="primary" type="submit" onClick={(e) => handleClick(e)}>
        <em className="aq-icon-settings"></em>Button
      </AqButton>
    </div>
  );
}

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

Components

Naming Convention in React

In React, Aqua DS components must be imported and used in PascalCase to ensure full compatibility with JSX. Unlike Vue, where components are often written in kebab-case, React requires component names to follow PascalCase (a variant of CamelCase) when rendered in JSX.

...
import { AqButton } from '@aqua-ds/react';
...

return (
  ...
  <AqButton variant="primary">Button</AqButton> <!-- ✅ Correct -->
	...
)

<aside> ❗

Avoid using <aq-button> in templates. It may not render correctly in some environments.

</aside>

Handling Component Events

Aqua DS components support standard React event handling. You can use event listeners like onClick, onChange, etc., as you would with native React elements.

The <AqButtonSplit> component from Aqua DS emits custom events such as onClickLeft, onClickRight, and onClickItem. These events can be handled using React's onEventName pattern, following camelCase convention.

Here is a full example:

import { AqButtonSplit } from '@aqua-ds/react';

export const ButtonSplitSet = ({ items }) => {
  const handleaqclickLeft = (e) => {
    console.log('Left button clicked', e);
  };

  const handleaqclickRight = (e) => {
    console.log('Right button clicked', e);
  };

  const handleaqclickItem = (e) => {
    console.log('Dropdown item clicked', e.detail); // Custom event data
  };

  return (
    <AqButtonSplit
      items={items || []}
      variant="success"
      size="medium"
      badge={{ number: 2, state: 'default' }}
      icon="aq-icon-send-money"
      onClickLeft={(e) => handleaqclickLeft(e)}
      onClickRight={(e) => handleaqclickRight(e)}
      onClickItem={(e) => handleaqclickItem(e)}
    >
      Button
    </AqButtonSplit>
  );
};

<aside> ℹ️

Note: Ensure the component you're using emits the event you're listening for. Event names follow the standard camelCase format in React.

</aside>

<aside> 💡

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

</aside>

Passing Properties to Components

When using Aqua DS components in React, you can pass properties directly as JSX props, just like with native React components.

Here's a practical example with the <AqButtonSplit /> component:

import { AqButtonSplit } from '@aqua-ds/react';

const items = [
  { id: '1', name: 'Option 1' },
  { id: '2', name: 'Option 2' },
];

const badge = { number: 2, state: 'default' };

export const ButtonSplitExample = () => {
  const handleaqclickLeft = (e: MouseEvent) => {
    console.log('Left button clicked', e);
  };

  const handleaqclickRight = (e: MouseEvent) => {
    console.log('Right button clicked', e);
  };

  const handleaqclickItem = (e: CustomEvent) => {
    console.log('Item clicked:', e.detail);
  };

  return (
    <AqButtonSplit
      items={items}
      variant="success"
      size="medium"
      badge={badge}
      icon="aq-icon-send-money"
      onClickLeft={handleaqclickLeft}
      onClickRight={handleaqclickRight}
      onClickItem={handleaqclickItem}
    >
      Button
    </AqButtonSplit>
  );
};

<aside> ✅

Properties like items, variant, badge, and icon are passed as standard props. Event handlers are bound using the onEventName convention.

</aside>

Two Way Binding

In React, two-way binding is typically achieved by using useState to store the component's value and updating it via an event handler like onChange.

Here is an example using <AqCheckbox>:

import { useState } from 'react';
import { AqCheckbox } from '@aqua-ds/react';

export const CheckboxExample = () => {
  const [checkedValue, setCheckedValue] = useState<string | undefined>(undefined);

  const handleValueChanged = (event: CustomEvent) => {
    const value = event.detail;
    setCheckedValue(value);
    console.log('Checkbox changed to:', value);
  };

  return (
    <AqCheckbox
      id-checkbox="checkbox-1"
      name="checkbox-1"
      label="This is a checkbox 1"
      icon="aq-icon-message"
      isRequired
      info="This is an information tooltip"
      value-checkbox="option-1"
      onChange={handleValueChanged}
    />
  );
};

✅ Use useState to track checkbox value changes via the onChange event handler.

🧠 value-checkbox represents the selected value passed to the component.

On this page