LogoLogo
HomeDiscourseBlogDiscord
  • Introduction
  • Introduction
    • Quick start
    • Aurelia for new developers
    • Hello world
      • Creating your first app
      • Your first component - part 1: the view model
      • Your first component - part 2: the view
      • Running our app
      • Next steps
  • Templates
    • Template Syntax
      • Attribute binding
      • Event binding
      • Text interpolation
      • Template promises
      • Template references
      • Template variables
      • Globals
    • Custom attributes
    • Value converters (pipes)
    • Binding behaviors
    • Form Inputs
    • CSS classes and styling
    • Conditional Rendering
    • List Rendering
    • Lambda Expressions
    • Local templates (inline templates)
    • SVG
  • Components
    • Component basics
    • Component lifecycles
    • Bindable properties
    • Styling components
    • Slotted content
    • Scope and context
    • CustomElement API
    • Template compilation
      • processContent
      • Extending templating syntax
      • Modifying template parsing with AttributePattern
      • Extending binding language
      • Using the template compiler
      • Attribute mapping
  • Getting to know Aurelia
    • Routing
      • @aurelia/router
        • Getting Started
        • Creating Routes
        • Routing Lifecycle
        • Viewports
        • Navigating
        • Route hooks
        • Router animation
        • Route Events
        • Router Tutorial
        • Router Recipes
      • @aurelia/router-lite
        • Getting started
        • Router configuration
        • Configuring routes
        • Viewports
        • Navigating
        • Lifecycle hooks
        • Router hooks
        • Router events
        • Navigation model
        • Current route
        • Transition plan
    • App configuration and startup
    • Enhance
    • Template controllers
    • Understanding synchronous binding
    • Dynamic composition
    • Portalling elements
    • Observation
      • Observing property changes with @observable
      • Effect observation
      • HTML observation
      • Using observerLocator
    • Watching data
    • Dependency injection (DI)
    • App Tasks
    • Task Queue
    • Event Aggregator
  • Developer Guides
    • Animation
    • Testing
      • Overview
      • Testing attributes
      • Testing components
      • Testing value converters
      • Working with the fluent API
      • Stubs, mocks & spies
    • Logging
    • Building plugins
    • Web Components
    • UI virtualization
    • Errors
      • Kernel Errors
      • Template Compiler Errors
      • Dialog Errors
      • Runtime HTML Errors
    • Bundlers
    • Recipes
      • Apollo GraphQL integration
      • Auth0 integration
      • Containerizing Aurelia apps with Docker
      • Cordova/Phonegap integration
      • CSS-in-JS with Emotion
      • DOM style injection
      • Firebase integration
      • Markdown integration
      • Multi root
      • Progress Web Apps (PWA's)
      • Securing an app
      • SignalR integration
      • Strongly-typed templates
      • TailwindCSS integration
      • WebSockets Integration
      • Web Workers Integration
    • Playground
      • Binding & Templating
      • Custom Attributes
        • Binding to Element Size
      • Integration
        • Microsoft FAST
        • Ionic
    • Migrating to Aurelia 2
      • For plugin authors
      • Side-by-side comparison
    • Cheat Sheet
  • Aurelia Packages
    • Validation
      • Validation Tutorial
      • Plugin Configuration
      • Defining & Customizing Rules
      • Architecture
      • Tagging Rules
      • Model Based Validation
      • Validation Controller
      • Validate Binding Behavior
      • Displaying Errors
      • I18n Internationalization
      • Migration Guide & Breaking Changes
    • i18n Internationalization
    • Fetch Client
      • Overview
      • Setup and Configuration
      • Response types
      • Working with forms
      • Intercepting responses & requests
      • Advanced
    • Event Aggregator
    • State
    • Store
      • Configuration and Setup
      • Middleware
    • Dialog
  • Tutorials
    • Building a ChatGPT inspired app
    • Building a realtime cryptocurrency price tracker
    • Building a todo application
    • Building a weather application
    • Building a widget-based dashboard
    • React inside Aurelia
    • Svelte inside Aurelia
    • Synthetic view
    • Vue inside Aurelia
  • Community Contribution
    • Joining the community
    • Code of conduct
    • Contributor guide
    • Building and testing aurelia
    • Writing documentation
    • Translating documentation
Powered by GitBook
On this page
  • Targeting CSS selectors
  • Targeting elements
  • Determining the position

Was this helpful?

Export as PDF
  1. Getting to know Aurelia

Portalling elements

An element in two places at once.

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

<div portal>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:

<div portal="#somewhere">My markup moves toto DIV with ID somewhere</div>

<div id="somewhere"><!-- The element will be portalled here --></div>

Target an element by class:

<div portal=".somewhere">My markup moves to DIV with class somewhere</div>

<div class="somewhere"><!-- The element will be portalled here --></div>

Target an element by tagName:

<div portal="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.

<div portal="target.bind: somewhereElement">My markup moves to beneath the body</div>

<div ref="somewhereElement"><!-- The element will be portalled here --></div>

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.

import { INode, resolve } from 'aurelia';

export class MyComponent {
    readonly element: HTMLElement = resolve(INode);
}

We can do things with the injected element instance, like access the parentElement or other non-standard scenarios you might encounter.

<div>
    <div class="header" portal="target.bind: element.parentElement"></div>
</div>

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

<div portal="target: body; position: afterbegin;">My markup moves to beneath the body by default</div>

In this example, our element will move to just after the opening body tag <body> the other values are self-explanatory.

PreviousDynamic compositionNextObservation

Last updated 1 year ago

Was this helpful?