Setup

Recommended Installation and Implementation

Install

$ npm i @aurodesignsystem/auro-formkit

Implementation

## Custom Component Registration for Version Management There are two key parts to every Auro component: the class and the custom element definition. The class defines the component’s behavior, while the custom element registers it under a specific name so it can be used in HTML. You can do this by importing only the component class and using the `register(name)` method with a unique name:

// Import the class only
import { AuroDropdown } from '@aurodesignsystem/auro-formkit/auro-dropdown/class';

// Register with a custom name if desired
AuroDropdown.register('custom-dropdown');

This will create a new custom element `` that behaves exactly like ``, allowing both to coexist on the same page without interfering with each other.

<custom-dropdown id="customCommon" layout="classic" shape="classic" size="lg" aria-label="Label content for screen reader">
  <div style="padding: var(--ds-size-150);">
    Lorem ipsum solar
    <br />
    <auro-button id="customCommonButton">
      Dismiss Dropdown
    </auro-button>
  </div>
  <span slot="helpText">
    Help text
  </span>
  <div slot="trigger">
    Trigger
  </div>
</custom-dropdown>

Auto Installation and Implementation

Warning: Default registration can cause conflicts if another package registers the same tag name using a different version of the component, leading to unexpected behavior. Use custom registration to avoid this risk.

Install

$ npm i @aurodesignsystem/auro-formkit

Implementation

Import the component, then register the custom element:

import '@aurodesignsystem/auro-formkit/auro-dropdown';

Then use the element in your HTML:

<auro-dropdown aria-label="custom label">
  Lorem ipsum solar
  <div slot="trigger">
    Trigger
  </div>
</auro-dropdown>

CDN Installation

Warning: CDN registration can cause conflicts if another package registers the same tag name using a different version of the component, leading to unexpected behavior. Use custom registration to avoid this risk.

The dropdown component can be loaded via CDN without a build step:

<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/auro-dropdown/+esm" type="module"></script>

Then use the element in your HTML:

<auro-dropdown aria-label="custom label">
  Lorem ipsum solar
  <div slot="trigger">
    Trigger
  </div>
</auro-dropdown>

Frameworks

React

React 19 includes native support for custom elements, so <auro-dropdown> works directly in JSX without any wrapper library. Import the Component Import and register the components at the top level of your application (e.g. in your root `main.tsx` or `App.tsx`):

import { AuroDropdown } from '@aurodesignsystem/auro-formkit/auro-dropdown/class';

AuroDropdown.register('[custom]-dropdown');

TypeScript Declarations The component ships with TypeScript type definitions for the `AuroDropdown` class. However, React's JSX does not automatically map custom element tag names to their types. To get type checking for `` in JSX, add the following declaration to a `.d.ts` file in your project:

import type { AuroDropdown } from '@aurodesignsystem/auro-formkit/auro-dropdown/class';

declare global {
  namespace JSX {
    interface IntrinsicElements {
      '[custom]-dropdown': React.HTMLAttributes<AuroDropdown> & Partial<AuroDropdown>;
    }
  }
}

Event Handling Auro components emit native `CustomEvent`s. Use a `ref` to attach event listeners in a `useEffect`:

import { useRef, useEffect } from 'react';

function MyDropdown() {
  const dropdownRef = useRef<HTMLElement>(null);

  useEffect(() => {
    const el = dropdownRef.current;
    if (!el) return;

    const handleToggle = () => {
      console.log('Dropdown toggled, isPopoverVisible:', (el as any).isPopoverVisible);
    };

    el.addEventListener('auroDropdown-toggled', handleToggle);
    return () => el.removeEventListener('auroDropdown-toggled', handleToggle);
  }, []);

  return (
    <custom-dropdown ref={dropdownRef}>
      <span slot="trigger">Open dropdown</span>
      <p>Dropdown content goes here</p>
    </custom-dropdown>
  );
}

Module Resolution Ensure your `tsconfig.json` uses `"moduleResolution": "bundler"` so TypeScript can resolve the component's package exports:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

Svelte

Svelte has native support for custom elements, so <auro-dropdown> works directly in Svelte templates without any wrapper or configuration. Import the Component Import and register the components in the `