Docebo libraries documentation site
v0.18.1
Get Started
Guides
Overview
Localization
Date and Timezone Durations Translations
Theme Typography Using Icons Using Illustrations
Components
Accordion Avatar Badge Alert Badge Icon Badge Status Blank Slate Breadcrumbs Button Calendar Card Carousel Chip Data Browser Expandable Content Facet List
Filters
Filter Filter Container Filter Multiple Selection Filter Single Selection Filter Slider Range Selection Filter Slider Selection
Helper Message Icon Illustration
Inputs
Input Autocomplete Input Checkbox Input Checkbox Group Input Combobox Input Date Input Password Input Radio Group Input Rating Input Search Input Select Input Slider Input Text Input Toggle Input Upload
Link List List Listbox List Navigation List Presentation List Sheet List Tablist List Tree
Media Players
Media Player Media Player Vimeo Media Player Wistia Media Player Youtube
Menu Modal Dialog Navigation Notification Pagination Bar Popover Progress Skeleton Stepper Table Toast Tooltip
CDK
Alert Errors Focus Disabled Keyboard Navigation Keyboard Navigation Manager Observe Content Observe Dimension Resizable Ripple Scrollable Container Size Validator Virtual Viewport
API References Elemental Ideas
CDK Virtual Viewport

Virtual Viewport

 Overview API Examples

The Virtual Viewport system provides a mechanism to define and manage distinct viewport areas within an application, primarily for controlling layout, overflow, and observing size changes. It allows an element to act as a boundary for its content, similar to the browser's main viewport but at a component level. This is particularly useful for features like tooltip positioning, container queries, or complex layout management where components need to be aware of their "local" viewport context.

Technical Overview

The Virtual Viewport feature comprises a service (LmnVirtualViewportService) and a directive (LmnVirtualViewportDirective). The directive marks an HTML element as a "virtual viewport," applying specific CSS properties for layout containment and container queries. The service manages these viewports, including their creation, destruction, and how they relate to each other (nesting).

The service also handles size change subscriptions, allowing components to react to dimension changes of their nearest virtual viewport. By default, the browser window itself is treated as the root virtual viewport.

Key Features

  • Virtual Viewport Creation: The lmnVirtualViewport directive designates an HTML element as a virtual viewport.
  • Viewport Management: The LmnVirtualViewportService manages a collection of these virtual viewports, including the main window viewport.
  • Viewport Hierarchy: The service can determine the nearest virtual viewport for any given element, enabling nested viewport contexts.
  • Size Change Observation: Components can subscribe to an observable (nearestVirtualViewportSizeChanges) provided by the service to react to size changes (debounced) of their containing virtual viewport.
  • Overflow Control: Virtual viewports can have their overflow programmatically hidden or shown using hideOverflow() and showOverflow() methods on the LmnVirtualViewport object, which toggles a CSS class (lmn-hide-overflow).
  • CSS Containment and Container Type: The directive applies contain: layout and a configurable container-type (defaulting to inline-size) CSS properties to the host element when active. This optimizes rendering performance and enables container queries.
  • Dynamic Activation: Virtual viewports can be activated or deactivated dynamically via the lmnVirtualViewportActive input on the directive.
  • Tooltip Integration: The directive includes LmnTooltipRootDirective as a host directive, suggesting integration with a tooltip system that might rely on viewport boundaries for positioning.
  • Server-Side Rendering (SSR) Safe: Activation and deactivation logic includes checks for isServerRendering() to avoid errors in non-browser environments.

When to Use

Use the Virtual Viewport system when:

  • You need to define specific layout boundaries within your application that are independent of the main browser window.
  • You intend to use CSS Container Queries for components within these boundaries.
  • Components or features (like custom tooltips, popovers, or complex scrollable areas) need to be aware of or constrained by a "local" viewport rather than the global one.
  • You need to observe and react to size changes of specific container elements in a structured way.
  • You want to optimize rendering performance for complex components by applying CSS containment.
  • You need to manage overflow for specific sections of your UI more granularly.

Implementation

LmnVirtualViewportDirective

Apply the lmnVirtualViewport directive to an HTML element to designate it as a virtual viewport.

Inputs:

  • lmnVirtualViewportActive: Optional (boolean, default: true). Determines if the virtual viewport is active. Setting it to false deactivates the viewport, removing its CSS properties and unregistering it from the service.
  • lmnVirtualViewportContainerType: Optional (string, default: 'inline-size'). Sets the container-type CSS property on the host element when the viewport is active. Common values might include 'size', 'inline-size', or 'normal'.
  • lmnVirtualViewportId: Optional (string, default: auto-generated unique ID like 'lmn-virtual-viewport-X'). A unique identifier for the virtual viewport.

Host Properties:

  • Adds class lmn-virtual-viewport.
  • Sets attribute data-lmn-virtual-viewport-id to the viewport's ID.
  • When active, sets data-lmn-virtual-viewport-active attribute.
  • Applies LmnTooltipRootDirective as a host directive.
Previous
Validator
Next
API References