Observe Dimension

The LmnObserveDimensionDirective is an Angular attribute directive that leverages the browser's ResizeObserver API to monitor and report changes in the dimensions of its host HTML element. It provides a simple way to react to size changes without manually managing ResizeObserver instances.

Technical Overview

The lmnObserveDimension directive, when applied to an HTML element, creates a ResizeObserver instance (if not in a server-side rendering context). This observer is then attached to the host element. When the host element's dimensions change (based on the configured lmnObserveDimensionConfig), the directive emits an event.

The directive handles the lifecycle of the ResizeObserver, including its creation, observation, and disconnection when the directive is destroyed or disabled.

Key Features

• Dimension Monitoring: Uses ResizeObserver to detect changes in the host element's size.
• Event Emission: Emits an LmnObserverDimensionEvent ({ element: HTMLElement, entries: ResizeObserverEntry[] }) when a dimension change is detected.
• Configurable Observer: Allows specifying ResizeObserverOptions (e.g., box property like 'content-box', 'border-box', or 'device-pixel-content-box') via an input.
• Disabled State: Observation can be dynamically enabled or disabled using an input.
• Lifecycle Management: Automatically creates the observer and disconnects it on destroy or when disabled.
• SSR Safe: Checks for server-side rendering to prevent errors when ResizeObserver is unavailable.
• Initial Emission: Emits an event with empty entries after the next render cycle if not disabled, allowing initial setup based on dimensions.

When to Use

Use the LmnObserveDimensionDirective when:

• You need to react to changes in an element's size to perform layout adjustments, trigger other actions, or update component state.
• You want a declarative way to use ResizeObserver without directly managing its lifecycle.
• You need detailed information about the nature of the size change, as provided by ResizeObserverEntry[].

Implementation

Apply the [lmnObserveDimension] directive to the HTML element you want to monitor.

Selector: [lmnObserveDimension]

Inputs:

• lmnObserveDimensionDisabled (alias disabled): Optional (boolean, default: false). If true, the ResizeObserver will be disconnected and no events will be emitted.
• lmnObserveDimensionConfig: Optional (ResizeObserverOptions, default: { box: 'content-box' }). Allows configuring the ResizeObserver instance (e.g., which box model to observe).

Outputs:

• lmnObserveDimension (alias event): Emits an LmnObserverDimensionEvent object when the host element's dimensions change. The event object contains:
  • element: HTMLElement: The host element being observed.
  • entries: ResizeObserverEntry[]: An array of ResizeObserverEntry objects detailing the changes. This array will be empty for the initial emission after render.