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 { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';

// Register with a custom name if desired
AuroForm.register('[custom]-form');

This will create a new custom element `` that behaves exactly like ``, allowing both to coexist on the same page without interfering with each other. ### Using Custom-Named Child Form Elements When consuming custom-named Auro form elements (like `auro-input` registered as `custom-input`), these elements _must_ be registered BEFORE auro-form due to rendering order limitations. Auro form elements are automatically recognized based on their tag name (e.g. `auro-input`) or special auro attributes which are only assigned during the initial render. For example, the following is correct:

import { AuroInput } from '@aurodesignsystem/auro-formkit/auro-input/class';
import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';

AuroInput.register('[custom]-input'); // adds an internal identifier auro-form uses to recognize the custom element
AuroForm.register('[custom]-form'); // render looks for said identifier

The following is NOT correct and will result in forms not working as expected:

import { AuroInput } from '@aurodesignsystem/auro-formkit/auro-input/class';
import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';

AuroForm.register('[custom]-form'); // forms start rendering, looking for auro inputs, or custom-named inputs
AuroInput.register('[custom]-input'); // too late, form has already rendered and did not find the custom element

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-form';

Then use the element in your HTML:

<auro-form>
  <auro-input name="searchBox" required>
    <span slot="label">Search flights</span>
  </auro-input>
  <br />
  <auro-button type="submit">Submit</auro-button>
</auro-form>

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.

Add the following script tag to your HTML to load the component directly from a CDN:

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

This script registers the <auro-form> custom element globally. You can then use it in your HTML:

<auro-form>
  <auro-input name="searchBox" required>
    <span slot="label">Search flights</span>
  </auro-input>
  <br />
  <auro-button type="submit">Submit</auro-button>
</auro-form>

Frameworks

React

React 19 includes native support for custom elements, so <auro-form> 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 { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';

AuroForm.register('[custom]-form');

TypeScript Declarations The component ships with TypeScript type definitions for the `AuroForm` 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 { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';

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

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

import { useRef, useEffect } from 'react';

function MyForm() {
  const formRef = useRef<HTMLElement>(null);

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

    const handleSubmit = (e: Event) => {
      console.log('Form values:', (e as CustomEvent).detail.value);
    };

    el.addEventListener('submit', handleSubmit);
    return () => el.removeEventListener('submit', handleSubmit);
  }, []);

  return (
    <custom-form ref={formRef}>
      {/* Add Auro form elements here */}
      <button type="submit">Submit</button>
    </custom-form>
  );
}

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-form> works directly in Svelte templates without any wrapper or configuration. Import the Component Import and register the components in the `