Aqua Basis

The AqFieldGroup component is a structural wrapper used to group input elements and controls within a consistent layout.

<aq-field-group label="This is a label" helper-text="Este es un texto de ayuda" info="Este es un tooltip"
  is-required is-error tooltip-width="20px">
  <aq-text-field placeholder="Este es un campo de texto" icon="aq-icon-settings"></aq-text-field>
</aq-field-group>

image 2 (1).png

It provides:

Default slot: to place form components (inputs, selectors, checkboxes, radios) or buttons.
Optional enhancements: labels, helper text, and tooltips for better accessibility and guidance.
Form support: handles error states, disabled states, and individual border styling.

This component is ideal for organizing related fields in complex forms, ensuring a cohesive user experience and maintaining visual hierarchy.

⚠️ Non-form components placed inside the default slot will render, but may not respect the layout and CSS styles.

Props and Attributes

Prop / Attr	Type	Default	Description
`helperText`	`string`	`''`	Additional text displayed below the form field group for guidance.
`label`	`string`	`''`	Main label displayed above the field group.
`info`	`string`	`''`	Tooltip content shown next to the label when hovered.
`tooltipWidth`	`string`	`''`	Sets the maximum width of the tooltip.
`borderMode`	`'group'	'individual'`	`'individual'`
`name`	`string`	`''`	Used to assign a group name for form or input association.
`isRequired`	`boolean`	`false`	Marks the fields in the group as required, usually shown with an asterisk.
`isReadonly`	`boolean`	`false`	Disables editing of the contained fields, making them read-only.
`isDisabled`	`boolean`	`false`	Disables the entire group of fields, making them inactive.
`isError`	`boolean`	`false`	Indicates an error state visually in the field group.
`isPlain`	`boolean`	`false`	Removes extra styles for a simpler, flat look.

PlayGround

You can interact with the component and experiment with its attributes and properties directly in this playground.

In the Code tab, the generated code snippet is available.

In addition to the interactive examples in this documentation, you can explore the full playground with all supported options and advanced configurations at the following link:

👉 Open full playground

https://aqua-ds-playground.masivianlabs.com/doc-storybook/index.html?path=/story/components-forms-aqfieldgroup--default&nav=0

<aside> ⚠️

Important: The code shown is in Web Component format. If you are using a specific framework (Vue, React, Angular), you must adapt it to the framework’s conventions before using it.

</aside>

Events

The AqFieldGroup component does not emit any events by itself.

Instead, events are triggered by the child components placed inside the default slot (e.g., AqInput, AqSelect, AqCheckbox).

This means that interaction events such as input, change, or click will come directly from the nested components, not from the AqFieldGroup wrapper.

Slots

The AqFieldGroup component is designed to provide a structured container for form elements. Its main feature is a default slot where developers can place other form components.

This slot is intended exclusively for form-related components (e.g., input fields, text areas, selectors, checkboxes, radios) or action elements such as buttons. When used inside the slot, these components will automatically follow the layout and styling rules defined by the design system.

<aq-flag-selector is-name="false" is-call-sign="false" placeholder="This is a placeholder"
  is-disabled="false"></aq-flag-selector>

<aq-text-field placeholder="This is a placeholder" icon="aq-icon-settings"></aq-text-field>

<aq-number-field id="aq-number-field-1" format="{thousandSeparated: true, mantissa: 1}"
  is-required></aq-number-field>

<aq-button is-outline>Button</aq-button>

⚠️ Note: If you attempt to render non-form components inside AqFieldGroup, they will still appear, but they will not inherit the expected layout or styling rules. To maintain proper design consistency, this component should only be used with form elements.

✅ Allowed content:

Form components (e.g., input fields, selectors, checkboxes, radios, text areas).
Action components such as buttons.

⚠️ Important: Adding components that do not belong to the forms category may cause them to render incorrectly or without the expected layout and CSS styles.

In Frameworks

Web Components

<aq-field-group
  label="This is a label"
  helper-text="Este es un texto de ayuda"
  info="Este es un tooltip"
  is-required
  is-error
>
  <!-- First child -->
  <aq-dropdown>
    <aq-button slot="activator" is-outline>
	    <em class="aq-icon-three-dots-vertical"></em>
    </aq-button>
  </aq-dropdown>
  <!-- Middle child -->
  <aq-text-field
    placeholder="Este es un campo de texto"
    icon="aq-icon-settings"
  ></aq-text-field>
  <!-- Last child -->
  <aq-button is-outline>Botón</aq-button>
</aq-field-group>

Vue

<template>
  <aq-field-group
    show-custom-counter
    :counter-source="['tag-1', 'tag-2']"
    :counter-limit="5"
    ref="fieldGroupRef"
    id="aq-field-group-1"
    label="This is a label"
    helper-text="Este es un texto de ayuda"
    info="Este es un tooltip"
    tooltip-width="20px"
    is-required
    is-error
  >
    <aq-flag-selector
      is-name
      is-call-sign
      placeholder="This is a placeholder"
      is-disabled"
    ></aq-flag-selector>
    <aq-text-field placeholder="This is a text field" icon="aq-icon-settings" />
    <aq-number-field format="{thousandSeparated: true, mantissa: 1}" is-required />
  </aq-field-group>
</template>

<script>
	import { defineComponent, ref } from 'vue';
	import {
		AqFieldGroup,
		AqFlagSelector,
		AqTextField,
		AqNumberField
	} from '@aqua-ds/vue';
	
	export default defineComponent({
	  components: {
	    AqFieldGroup,
	    AqFlagSelector,
	    AqTextField,
	    AqNumberField
	  }
	});
</script>

React

import { useRef } from 'react';
import {
	AqFieldGroup,
	AqFlagSelector,
	AqTextField,
	AqNumberField
} from '@aqua-ds/react';

export const FieldGroupSet = () => {
	  return (
	    <AqFieldGroup
	        id="aq-field-group-1"
	        showCustomCounter
	        counterSource={['tag-1', 'tag-2']}
	        counterLimit={5}
	        label="This is a label"
	        helperText="This is a helper text"
	        info="This is a tooltip"
	        tooltipWidth="20px"
	        isRequired
	        isError
	      >
	        <AqFlagSelector
	          isName={false}
	          isCallSign={false}
	          placeholder="This is a placeholder"
	          isDisabled={false}
	        />
	        <AqTextField placeholder="Este es un campo de texto" icon="aq-icon-settings" />
	        <AqNumberField format='{thousandSeparated: true, mantissa: 1}' isRequired />
	      </AqFieldGroup>
    </>
  );
}

Angular

// field-group-set.component.ts
import { Component } from '@angular/core';
import {
  AqFieldGroup,
  AqButton,
  AqTextField,
  AqNumberField,
  AWCValueAccessor,
} from '@aqua-ds/angular';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';

@Component({
  selector: 'app-field-group',
  standalone: true,
  imports: [
    AqFieldGroup,
    AqButton,
    AqTextField,
    AqNumberField,
    AWCValueAccessor,
    FormsModule,
    ReactiveFormsModule,
  ],
  templateUrl: './field-group-set.component.html',
})
export class SetFieldGroupComponent {
  textfieldValue = '';

  handleAqInput(e: any) {
    console.log('Handling aqinput from text field:', e.detail.value);
  }

  handleAqChange(e: any) {
    console.log('Handling aqchange from text field:', e.detail.value);
  }
}

<!-- field-group-set.component.html -->

<aq-field-group
  label="This is a label"
  helper-text="This is a helper text"
  info="This is a tooltip"
  is-required
>
  <aq-button is-outline>Button</aq-button>

  <aq-text-field
    [(ngModel)]="textfieldValue"
    placeholder="This is a placeholder"
    icon="aq-icon-settings"
    (aqInput)="handleAqInput($event)"
    (aqChange)="handleAqChange($event)"
  ></aq-text-field>

  <aq-number-field
    format="{thousandSeparated: true, mantissa: 1}"
    is-required
  ></aq-number-field>
</aq-field-group>