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 { AuroCheckbox, AuroCheckboxGroup } from '@aurodesignsystem/auro-formkit/auro-checkbox/class';

// Register with a custom name if desired
AuroCheckbox.register('custom-checkbox');
AuroCheckboxGroup.register('custom-checkbox-group');

This will create a new custom element >custom-checkbox< and >custom-checkbox-group< that behaves exactly like >auro-checkbox< and <auro-checkbox-group>, allowing both to coexist on the same page without interfering with each other.

<custom-checkbox-group>
  <span slot="legend">Form label goes here</span>
  <custom-checkbox value="value1" name="custom" id="checkbox-custom1">Custom checkbox option</custom-checkbox>
  <custom-checkbox value="value2" name="custom" id="checkbox-custom2" checked>Custom checkbox option</custom-checkbox>
  <custom-checkbox value="value3" name="custom" id="checkbox-custom3">Custom checkbox option</custom-checkbox>
  <custom-checkbox value="value4" name="custom" id="checkbox-custom4">Custom checkbox option</custom-checkbox>
</custom-checkbox-group>

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

Once installed, the component can be used in your project by importing the component's registered module:

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

This import registers the <auro-checkbox> and <auro-checkbox-group> custom elements globally. You can then use them in your HTML:

<auro-checkbox-group>
  <span slot="legend">Choose your options</span>
  <auro-checkbox value="option1" name="default" id="cb1">Option 1</auro-checkbox>
  <auro-checkbox value="option2" name="default" id="cb2">Option 2</auro-checkbox>
</auro-checkbox-group>

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-checkbox/+esm"></script>

This script registers the <auro-checkbox> and <auro-checkbox-group> custom elements globally. You can then use them in your HTML:

<auro-checkbox-group>
  <span slot="legend">Choose your options</span>
  <auro-checkbox value="option1" name="cdn" id="cb-cdn1">Option 1</auro-checkbox>
  <auro-checkbox value="option2" name="cdn" id="cb-cdn2">Option 2</auro-checkbox>
</auro-checkbox-group>

Frameworks

React

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

AuroCheckbox.register('[custom]-checkbox');
AuroCheckboxGroup.register('[custom]-checkbox-group');

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

declare global {
  namespace JSX {
    interface IntrinsicElements {
      '[custom]-checkbox': React.HTMLAttributes<AuroCheckbox> & Partial<AuroCheckbox>;
      '[custom]-checkbox-group': React.HTMLAttributes<AuroCheckboxGroup> & Partial<AuroCheckboxGroup>;
    }
  }
}

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

import { useRef, useEffect } from 'react';

function MyCheckboxGroup() {
  const groupRef = useRef<HTMLElement>(null);

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

    const handleInput = () => {
      console.log('Selected values:', (el as any).value);
    };

    el.addEventListener('input', handleInput);
    return () => el.removeEventListener('input', handleInput);
  }, []);

  return (
    <custom-checkbox-group ref={groupRef}>
      <span slot="legend">Select options</span>
      <custom-checkbox value="option1" name="example">Option 1</custom-checkbox>
      <custom-checkbox value="option2" name="example">Option 2</custom-checkbox>
    </custom-checkbox-group>
  );
}

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