Vaadin WC API reference

AppLayout

View as MD

Description

<vaadin-app-layout> is a Web Component providing a quick and easy way to get a common application layout structure done.

<vaadin-app-layout primary-section="navbar|drawer">
 <vaadin-drawer-toggle slot="navbar [touch-optimized]"></vaadin-drawer-toggle>
 <h3 slot="navbar [touch-optimized]">Company Name</h3>
 <vaadin-tabs orientation="vertical" slot="drawer">
   <vaadin-tab>Menu item 1</vaadin-tab>
 </vaadin-tabs>
 <!-- Everything else will be the page content -->
 <div>
   <h3>Page title</h3>
   <p>Page content</p>
 </div>
</vaadin-app-layout>

For best results, the component should be added to the root level of your application (i.e., as a direct child of <body>).

The page should include a viewport meta tag which contains viewport-fit=cover, like the following:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

This causes the viewport to be scaled to fill the device display. To ensure that important content is displayed, use the provided css variables.

--safe-area-inset-top
--safe-area-inset-right
--safe-area-inset-bottom
--safe-area-inset-left

Styling

The following Shadow DOM parts of the <vaadin-app-layout> are available for styling:

Part name Description
backdrop Backdrop covering the layout when drawer is open as an overlay
navbar Container for the navigation bar
drawer Container for the drawer area

See Styling Components documentation.

Component's slots

The following slots are available to be set

Slot name Description
no name Default container for the page content
navbar Container for the top navbar area
drawer Container for an application menu
touch-optimized Container for the bottom navbar area (only visible for mobile devices)

Touch optimized

App Layout has a pseudo-slot touch-optimized in order to give more control of the presentation of elements with slot[navbar]. Internally, when the user is interacting with App Layout from a touchscreen device, the component will search for elements with slot[navbar touch-optimized] and move them to the bottom of the page.

As the drawer opens as an overlay in small devices, it makes sense to close it once a navigation happens. If you are using Vaadin Router, this will happen automatically unless you change the closeDrawerOn event name.

In order to do so, there are two options:

  • If the vaadin-app-layout instance is available, then drawerOpened can be set to false
  • If not, a custom event close-overlay-drawer can be dispatched either by calling window.dispatchEvent(new CustomEvent('close-overlay-drawer')) or by calling AppLayout.dispatchCloseOverlayDrawerEvent()

Scrolling areas

By default, the component will act with the "body scrolling", so on mobile (iOS Safari and Android Chrome), the toolbars will collapse when a scroll happens.

To use the "content scrolling", in case of the content of the page relies on a pre-defined height (for instance, it has a height:100%), then the developer can set height: 100% to both html and body. That will make the [content] element of app layout scrollable. On this case, the toolbars on mobile device won't collapse.

Properties

closeDrawerOn

Type: string

A global event that causes the drawer to close (be hidden) when it is in overlay mode.

  • The default is vaadin-router-location-changed dispatched by Vaadin Router

drawerOpened

Type: boolean

Controls whether the drawer is opened (visible) or not. Its default value depends on the viewport:

  • true, for desktop size views
  • false, for mobile size views

i18n

Type: AppLayoutI18n

The object used to localize this component. To change the default localization, replace this with an object that provides all properties, or just the individual properties you want to change.

The object has the following structure and default values:

{
  drawer: 'Drawer'
}

See also: AppLayoutI18n

overlay

Type: boolean

Drawer is an overlay on top of the content Controlled via CSS using --vaadin-app-layout-drawer-overlay: true|false;

primarySection

Type: "drawer" | "navbar"

Defines whether navbar or drawer will come first visually.

  • By default (primary-section="navbar"), the navbar takes the full available width and moves the drawer down.
  • If primary-section="drawer" is set, then the drawer will move the navbar, taking the full available height.

Static Methods

dispatchCloseOverlayDrawerEvent

Type: () => void

Helper static method that dispatches a close-overlay-drawer event

Events

close-overlay-drawer

Type: CustomEvent

App Layout listens to close-overlay-drawer on the window level. A custom event can be dispatched and the App Layout will close the drawer in overlay.

That can be used, for instance, when a navigation occurs when user clicks in a menu item inside the drawer.

See dispatchCloseOverlayDrawerEvent() helper method.

drawer-opened-changed

Type: AppLayoutDrawerOpenedChangedEvent

Fired when the drawerOpened property changes.

overlay-changed

Type: AppLayoutOverlayChangedEvent

Fired when the overlay property changes.

primary-section-changed

Type: AppLayoutPrimarySectionChangedEvent

Fired when the primarySection property changes.

Types

AppLayoutDrawerOpenedChangedEvent 

/**
 * Fired when the `drawerOpened` property changes.
 */
export type AppLayoutDrawerOpenedChangedEvent = CustomEvent<{ value: boolean }>;

AppLayoutI18n 

export interface AppLayoutI18n {
  drawer?: string;
}

AppLayoutOverlayChangedEvent 

/**
 * Fired when the `overlay` property changes.
 */
export type AppLayoutOverlayChangedEvent = CustomEvent<{ value: boolean }>;

AppLayoutPrimarySectionChangedEvent 

/**
 * Fired when the `primarySection` property changes.
 */
export type AppLayoutPrimarySectionChangedEvent = CustomEvent<{ value: 'drawer' | 'navbar' }>;