<oim-player> API Reference

The custom element interface for rendering Object Interactive Media (OIM) images and handling dynamic layer overlays.

Element Registration

The player is registered under the custom tag <oim-player>. Ensure the component script is loaded to register it in the document:

<script src="https://cdn.oim.media/oim-player.js"></script>

HTML Attributes

Attribute	Type	Default	Description
src	string	""	Source URL of the .oim target asset.
lang	string	"en"	Language code used to resolve localized slot content.
fit	"contain" | "cover"	"contain"	Viewport scale and container fit behavior.
align	"center" | "top" | "bottom"	"center"	Vertical alignment of the interactive media canvas.
allow-lottie	boolean	true	Enables rendering of Lottie vector animations in slots.
disable-animations	boolean	from mode	Suspends active hover effects, loop runs, and pauses Lottie animations.
mode	"image" | "full"	"image"	Preset for the two capability flags below. image is a still picture with its language; full moves and responds. An explicit flag overrides the preset.
disable-actions	boolean	from mode	Suspends click and hover actions declared in the file. Not affected by prefers-reduced-motion: that is a vestibular preference about motion, not a waiver of the ability to interact.
auto-rotate-lang	number | "false"	"false"	Dynamic language rotation interval in milliseconds.
placeholder	string	none	Thumbnail shown until the player paints. Only http:, https:, blob: and data:image/ URLs are used.
activate-on	"visible" | "hover" | "manual"	"visible"	hover moves the file only under the pointer (touch devices behave as visible); manual leaves it to play() and pause().
palette	string	file default	Name of one of the file's palettes. Unknown names are ignored.
show-slots	boolean	true	false draws only the base image.

JavaScript Properties & Methods

In addition to standard HTML attributes, the following JS interface is available on the element node:

Properties

• player.src: String (gets or sets the active asset URL).
• player.lang: String (gets or sets the active language).
• player.fit: String (gets or sets the viewport containment mode).

Methods

• player.setLang(langTag: string): void - Updates the current language tag in real time.
• player.setZoom(scale: number): void - Configures the viewport scale factor (range 1.0 to 4.0).
• player.play(): void - Starts language rotation cycle.
• player.pause(): void - Pauses language rotation cycle.

Custom Events

The component dispatches standard custom events on state changes:

oim:loaded

Dispatched when the metadata has been extracted, validated, and overlay elements have mounted.

• Payload (event.detail):

  {
    type: "image",
    metadata: OimMetadata
  }

• Usage:

  player.addEventListener('oim:loaded', (e) => {
    console.log('OIM Loaded:', e.detail.metadata);
  });

oim:action

Dispatched when a slot's declared action runs. The file cannot cause anything on its own: it has no handler, no URL and no destination outside itself — it only announces, and only matters if the page listens.

• Payload (event.detail):

  {
    slot: string,      // id of the slot — stable, what `targets` use
    name?: string,     // the layer name the author typed — what you can read
    trigger: "click" | "hover",
    targets: string[], // ids of the affected slots
    types: string[]    // "show" | "hide" | "toggle" | "setText"
  }

• Cancelable: preventDefault() suppresses the local effect, so a page can decide click by click.

• Fires for any interactive layer, even one with no declared actions — a layer the author marked interactive announces its click with empty targets. Ids are generated, so listen by name; names are not unique.

• Usage:

  player.addEventListener('oim:action', (e) => {
    // If you want a click to navigate, the PAGE decides — with its own URL.
    if (e.detail.name === 'Buy') window.location.href = '/product/42';
  });