# 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:

```typescript
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

```typescript
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 { }
```

```html
<!-- 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.