Skip to content

Module: src/core/Dom

This component manages the root DOM structure of the player. It is responsible for injecting, replacing, or appending the root wrapper element, according to the configured placement mode. All internal components depend on this element being mounted and available, as it acts as the main container and layout context for the entire player. It also includes layout logic for aspect ratio handling and emits well-defined lifecycle events for DOM readiness. Furthermore, this component also manages CSS styles and can insert it at different locations, with Vite HMR and Sourcemaps still intact while developing. This also enables support for Shadow DOM, so the player can be completely shielded against outer DOM and style access.

Version
1.0.0
Author
Frank Kudermann - alphanull
License
MIT
Requires
object
sortElements
DomSmith
domSmithInputRange
domSmithSelect
domSmithTooltip
Source
Dom.js, line 29

Constructor

new Dom(player, parent, optionsopt)

Creates an instance of the Dom component. Also prepares the root dom element based on the player config.

Parameters:
Name Type Attributes Description
player Player

Reference to the VisionPlayer instance.
parent Player

Reference to the parent instance.
options Object optional

Additional options.

Parameters:
Name Type Attributes Description
apiKey symbol optional

Token for extended access to the player API.
Throws

If trying to disable this component.

Type Error

Members

Holds the instance configuration for this component.

Properties
Name Type Attributes Default Description
shadow 'open' | 'closed' | '' optional ''

Shadow DOM mode: 'closed', 'open', or '' (no Shadow DOM). If enabled, all player UI is rendered inside a shadow root for encapsulation and style isolation.
className string optional ''

Sets a custom classname on the player instance.
insertMode 'auto' | 'replace' | 'append' | 'before' optional 'auto'

Where insertMode defines how the player is inserted into the DOM in conjunction with the target element. Can have the following values: auto generally appends to target, but replaces media elements and elements with a vip-data-media attribute, append treats the target element as parent to attach to, replace replaces the target element while before inserts the player before the target.
darkMode 'dark' | 'light' | 'auto' optional 'dark'

Sets the preferred visual mode for the player: dark, light, or auto for using system defaults.
layout string optional ''

Activates special layout modes. Currently supported: controller-only: Displays only the control interface (no video, canvas, or overlays). Used for audio playback.
aspectRatio number | string optional 16/9

Defines the aspect ratio of the player. Can be a numeric value like 16/9 or 1.777, 'auto' to automatically adapt to the current video, or fill to make layout depend on the container. Ignored when both width and height are defined.
aspectRatioTransitions boolean optional false

If true, aspect ratio changes are animated (if supported by the browser).
width number | string optional 100%

Optional fixed width. If set as a number, it will be interpreted as pixels. If set as a string, it will be passed as-is to the CSS (e.g. 80vw).
height number | string optional ''

Optional fixed height. If set as a number, it will be interpreted as pixels. If set as a string, it will be passed as-is to the CSS (e.g. 80vh).
_targetEle HTMLElement optional nullable null

The original target element calculated or received from the first new VisionPlayer argument. INTERNAL USE ONLY, not part of the official config.
Type
Object
Source
Dom.js, line 45

Reference to the main player instance.

Type
Player
Source
Dom.js, line 62

Holds tokens of subscriptions to player events, for later unsubscribe.

Type
Array<number>
Source
Dom.js, line 68

Secret key only known to the player instance and initialized components. Used to be able to restrict access to API methods in conjunction with secure mode.

Type
symbol
Source
Dom.js, line 75

Reference to the root element of the player.

Type
HTMLElement
Source
Dom.js, line 81

Reference to the original target Element.

Type
HTMLElement
Source
Dom.js, line 87

Reference to the ShadowRoot instance (if enabled).

Type
ShadowRoot
Source
Dom.js, line 93

Reference to the top-level wrapper node, which will be used when shado wmode is active.

Type
HTMLElement
Source
Dom.js, line 99

Map holding all style elements for live updates (key: style id/url, value: <style> node).

Type
Map<string, HTMLStyleElement>
Source
Dom.js, line 105

Global map holding all loaded style contents (key: absolute style path, value: CSS).

Type
Map<string, string>
Source
Dom.js, line 401

Set of all current Dom component instances.

Type
Set<Dom>
Source
Dom.js, line 407

Methods

private #initStyles()

Injects all global stylesheets into the current scope (head or Shadow DOM).

Source
Dom.js, line 270

private #refresh()

Called - via private API - from the player class if all components have been reloaded due to a config change. Resorts the root Dom and fires events again so components can catch up.

Fires
dom/ready
dom/beforemount
Source
Dom.js, line 315

private #mount()

Inserts the root dom element into the host document.

Fires
dom/ready
dom/beforemount
Source
Dom.js, line 329

private #getElement(apiKey) → HTMLElement

Used by child components to retrieve the player root element. Access is restricted by apiKey if secure mode is enabled.

Parameters:
Name Type Description
apiKey symbol

Token needed to grant access in secure mode.
Returns

The player root element.

Type HTMLElement
Throws

If called in secure mode without valid key.

Type Error
Source
Dom.js, line 351

updateStyles(styles)

Updates the content of all style elements in this instance using the provided array of style objects. Used for live HMR updates.

Parameters:
Name Type Description
styles Array<{key: string, css: string}>

Array of style updates (key: style id/url, css: new content).
Source
Dom.js, line 365

destroy()

Cleans up the Dom component by unsubscribing from events and removing style elements.

Source
Dom.js, line 376

static initialize(Player)

Registers API hooks on the Player class for style injection and HMR update.

Parameters:
Name Type Description
Player Player

Reference to the Player constructor.
Source
Dom.js, line 413

private, static #addStyles(path, css)

Adds a style sheet to the global styles map (used by all player instances).

Parameters:
Name Type Description
path string

Relative or absolute style path (e.g., 'assets/scss/core/player.scss').
css string

Raw CSS string (usually imported with ?inline).
Source
Dom.js, line 425

private, static #updateStyles(styles)

Triggers an updateStyles call on all Dom instances, used for HMR.

Parameters:
Name Type Description
styles Array<{key: string, css: string}>

Array of updated styles (key/url, css string).
Source
Dom.js, line 436

Events

dom/beforemount

This event is fired when the player has initialized all components, but is not added to the DOM yet.

Listeners
Controller#sortButtons
Source
Dom.js, line 446

dom/ready

This event is fired when the player was just added to the target DOM.

Listeners
Scrubber#onDomReady
UI#onDomReady
Source
Dom.js, line 451