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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aurelia.io/developer-guides/error-messages/runtime-html/aur0501.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.