AUR0717

Template compilation error: detected a usage of "<slot>" element without specifying shadow DOM options in element yyyy

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:

  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:

// 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):

// 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):

// 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 { }

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

See the Shadow DOM guide for more details on enabling Shadow DOM, and the Slotted Content guide for more information about slots and content projection.