There are situations that some elements of a custom element should be rendered at a different location within the document, usually at the bottom of a document body or even inside of another element entirely. Aurelia supports this intuitively with the portal custom attribute.
While the location of the rendered element changes, it retains its current binding context. A great use for the portal attribute is when you want to ensure an element is displayed in the proper stacking order without needing to use CSS hacks like z-index:9999
Using the portal attribute without any configuration options will portal the element to beneath the document body (before the closing body tag).
<divportal>My markup moves to beneath the body by default</div>
Targeting CSS selectors
If you want to choose where a portalled element is moved to, you can supply a CSS selector where it should be moved.
Target an element with an ID of somewhere:
<divportal="#somewhere">My markup moves toto DIV with ID somewhere</div><divid="somewhere"><!-- The element will be portalled here --></div>
Target an element by class:
<divportal=".somewhere">My markup moves to DIV with class somewhere</div><divclass="somewhere"><!-- The element will be portalled here --></div>
Target an element by tagName:
<divportal="body">My markup moves to beneath the body (just before the closing tag)</div>
Targeting elements
The portal attribute can also reference other elements with a ref attribute on them.
You can also target elements not using the ref attribute too. A good example is a custom element. Maybe you want to portal a section of a child element to the parent element.
We can do things with the injected element instance, like access the parentElement or other non-standard scenarios you might encounter.
You could also do this with query calls such as querySelector and so forth as well aliased to class properties.
Determining the position
By default, the portal attribute will portal your elements before the closing tag of your target. By default using portal without any configuration values will portal it just before the closing </body> tag.
We can override this behavior using the position property and the following values:
beforebegin
afterbegin
beforeend (the default value)
afterend
In this example, our element will move to just after the opening body tag <body> the other values are self-explanatory.
<div portal="target.bind: somewhereElement">My markup moves to beneath the body</div>
<div ref="somewhereElement"><!-- The element will be portalled here --></div>
import { INode } from 'aurelia';
export class MyComponent {
constructor(@INode readonly element: HTMLElement) {}
}
