# AUR0717

### **Error message**

Template compilation error: detected a usage of `"<slot>"` element without specifying shadow DOM options in element: {{0}}

### **Parameters**

1. `elementName`: The name of the custom element where the `<slot>` was found.

### Error explanation

This error occurs during template compilation when a `<slot>` element is used within a custom element's template, but the custom element has not been configured to use Shadow DOM. The native `<slot>` element is part of the Shadow DOM specification and only functions correctly when the component has `shadowOptions` defined.

Aurelia's `au-slot` attribute provides a slotting mechanism that works *without* Shadow DOM, but the native `<slot>` element requires it.

### Common causes

* Using `<slot>` (or `<slot name="...">`) in a custom element's template without setting `shadowOptions` in the element's definition.
* Migrating from a framework where `<slot>` might work without Shadow DOM, or confusing it with Aurelia's `au-slot` attribute for content projection.

### How to fix

* **Option 1 (Use Shadow DOM):** If you intend to use native Shadow DOM slots, add `shadowOptions` to your custom element definition or use the `@useShadowDOM` decorator:

  ```typescript
  import { customElement, useShadowDOM } from 'aurelia';

  @customElement({
    name: 'my-element',
    template: `<div><slot></slot></div>`,
    shadowOptions: { mode: 'open' } // or 'closed'
  })
  export class MyElement { }

  // Or use the decorator:
  @customElement('my-element')
  @useShadowDOM({ mode: 'open' })
  export class MyElement { }
  ```
* **Option 2 (Use au-slot for projection without Shadow DOM):** If you do *not* want to use Shadow DOM, replace the `<slot>` element in your template with the target element where you want projected content to appear, and use the `au-slot` attribute on the content being projected when using the component. Aurelia's default slot projection mechanism (without explicit `<slot>` tags in the component template) often handles simple cases automatically.

### Example of Incorrect Usage:

```typescript
// my-element.ts
import { customElement } from 'aurelia';

@customElement({
  name: 'my-element',
  // Error: Using <slot> without shadowOptions
  template: `<div><slot></slot></div>`
})
export class MyElement { }
```

### Example of Correct Usage (with Shadow DOM):

```typescript
// my-element.ts
import { customElement, useShadowDOM } from 'aurelia';

@customElement({
  name: 'my-element',
  template: `<div><slot></slot></div>`,
  shadowOptions: { mode: 'open' } // Correct: Shadow DOM enabled
})
export class MyElement { }

// Or using the decorator:
@customElement('my-element')
@useShadowDOM()
export class MyElement { }
```

### Example of Correct Usage (without Shadow DOM, using au-slot):

```typescript
// my-element-no-shadow.ts
import { customElement } from 'aurelia';

@customElement({
  name: 'my-element-no-shadow',
  template: `<div><au-slot></au-slot></div>`
})
export class MyElementNoShadow { }
```

```html
<!-- usage.html -->
<my-element-no-shadow>
  This content will be projected into the au-slot.
</my-element-no-shadow>
```

See the [Shadow DOM guide](https://github.com/aurelia/aurelia/blob/master/docs/user-docs/developer-guides/components/shadow-dom.md) for more details on enabling Shadow DOM, and the [Slotted Content guide](https://github.com/aurelia/aurelia/blob/master/docs/user-docs/developer-guides/components/shadow-dom-and-slots.md) for more information about slots and content projection.


---

# 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/0088-to-0723/aur0717.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.