AUR0501

Error Message

AUR0501: Invalid combination: cannot combine the containerless custom element option with Shadow DOM.

Description

This error occurs when a custom element is defined with both the containerless attribute/option and a shadowOptions configuration (indicating the use of Shadow DOM). These two features are mutually exclusive.

Cause

The fundamental conflict arises from the nature of containerless and Shadow DOM:

• containerless: This option tells Aurelia to render the content of the custom element's template directly into the parent DOM, omitting the custom element's host element itself.

• Shadow DOM: This feature requires a host element to attach the shadow root to. The shadow root encapsulates the element's internal DOM structure.

Since containerless removes the host element, there is no element left to attach a shadow root to, making the combination impossible.

You have likely configured a custom element like this:

import { customElement, containerless } from 'aurelia';

// Incorrect combination:
@customElement({
  name: 'my-element',
  template: '...',
  containerless: true, // Option 1
  shadowOptions: { mode: 'open' } // Option 2 - Conflict!
})
export class MyElement { }

// Or using the @containerless decorator:
@containerless()
@customElement({
  name: 'my-element',
  template: '...',
  shadowOptions: { mode: 'open' } // Still conflicts!
})
export class MyElement { }

Solution

You must choose between using containerless or Shadow DOM for your component.

1. If you need Shadow DOM: Remove the containerless: true option or the @containerless decorator from your custom element definition. The component will render with its host element, allowing the shadow root to be attached.

2. If you need containerless: Remove the shadowOptions configuration from your custom element definition. The component's template content will be rendered directly without a host element or Shadow DOM encapsulation.

Example

import { customElement, containerless } from 'aurelia';

// --- Option 1: Using Shadow DOM (Remove containerless) ---
@customElement({
  name: 'my-shadow-element',
  template: '<div class="internal">Shadow Content</div>',
  // containerless: true, // REMOVED
  shadowOptions: { mode: 'open' } // KEEP
})
export class MyShadowElement { }

// --- Option 2: Using Containerless (Remove shadowOptions) ---
@customElement({
  name: 'my-containerless-element',
  template: '<div class="internal">Containerless Content</div>',
  containerless: true, // KEEP
  // shadowOptions: { mode: 'open' } // REMOVED
})
@containerless() // Or using the decorator form
export class MyContainerlessElement { }

<!-- Usage Example -->

<!-- Renders as: <my-shadow-element> #shadow-root <div class="internal">...</div> </my-shadow-element> -->
<my-shadow-element></my-shadow-element>

<!-- Renders as: <div class="internal">Containerless Content</div> -->
<my-containerless-element></my-containerless-element>

Debugging Tips

• Inspect the custom element definition (@customElement({...}) or decorator usage) for the component mentioned in the error or stack trace.

• Look for the simultaneous presence of containerless (either as a boolean property containerless: true or the @containerless() decorator) and the shadowOptions property.

• Decide which rendering mode is appropriate for the component's purpose and remove the conflicting option.