Umbraco UI Library (UUI)

The uui-card is a base card component that supports several states and interactions, including:

• Selection states
• Error states
• Optional link or button interactions

If npm link causes issues with workspace hoisting, you can use the file: protocol in the consumer's package.json. This copies the package instead of symlinking it.

Warning: Because it copies the files, you must run npm install every time you rebuild UUI to see changes.

// In the consumer's package.json
{
  "dependencies": {
    "@umbraco-ui/uui": "file:../../../Umbraco.UI"
  }
}

The UUIFormControlMixin maintains its v1 surface (including name, required, error, submit(), etc.). However, v2 introduces a split to allow for more control:

• UUIFormControlMixin: The full surface (base + basics). This is an alias for UUIFormControlWithBasicsMixin.
• UUIFormControlBaseMixin: A lean core containing only form association, value, pristine, and validator machinery. Use this when you want full control over properties and validators.

Types for the lean base are exported as UUIFormControlBaseMixinElement/UUIFormControlBaseMixinInterface.

Use UUIFormControlBaseMixin when you need a lightweight core for form association without the standard 'basics' provided by the full mixin. This is ideal when your component requires full manual control over its own properties and validation logic.

This mixin provides:

• Form association
• value: The current value of the control.
• pristine: State indicating if the control has been interacted with.
• Validator machinery: The underlying infrastructure to handle validation without the pre-configured required or error properties.

Umbraco UI tracks loaded versions on the global object. When UUI loads, it appends its version to globalThis.__uuiVersions.

If multiple copies of UUI are present on the same page (such as duplicate bundles or mismatched versions), a warning will be emitted to the console: Multiple versions of Umbraco UI detected: [version1], [version2]. This is not supported and may cause issues.

You can manually inspect the globalThis.__uuiVersions array to diagnose version conflicts.

// Inspect the array of loaded versions for diagnostics
console.log(globalThis.__uuiVersions); // e.g. ["2.0.0"]

When creating or working with UUI components, follow these specific naming rules:

Use UUIFormControlMixin (also exported as UUIFormControlWithBasicsMixin) to make a web component fully compatible with forms. This is the complete version that matches the v1 surface. It provides standard form properties and built-in validation logic.

It adds the following properties and methods to your component:

• name: The name of the control.
• required: Boolean indicating if the field is mandatory.
• requiredMessage: Custom message for required validation.
• error: Error state indicator.
• errorMessage: The message to display when an error occurs.
• submit(): Method to trigger form submission logic.
• valueMissing and customError: Built-in validators that work on top of the base functionality.

You can create a custom icon registry that loads icons on demand by extending the UUIIconRegistry class. You must implement the acceptIcon(iconName) method. Inside this method, you can use this.provideIcon(iconName) to get an icon object and then assign the SVG data to its svg property.

import { UUIIconRegistry } from '@umbraco-ui/uui/components/icon-registry/UUIIconRegistry.js';

class MyIconRegistry extends UUIIconRegistry {
  protected acceptIcon(iconName) {
    const icon = this.provideIcon(iconName);
    // Load and assign SVG data:
    icon.svg = '<svg>...</svg>';
    return true;
  }
}