GitHub
Component Guide

Lumens Starmap Banner

`@briangershon/lumens-starmap-banner` is an interactive custom element for adding a transparent animated sky with visible stars, constellations, and exotic unseen objects to a host layout.

@briangershon/lumens-starmap-banner
<lumens-starmap-banner>
Event: starmap-object-selected
Back to docs index Jump to starter example
Live Preview

Preview the shipped browser bundle

The demo below imports the built browser bundle that Lumens docs publish, so the page reflects the component contract consumers can load directly. Each preview also demonstrates a recommended host-owned hover detail overlay layered in front of the banner.

Light host example Hover a visible star or unseen object to see a host-owned overlay driven by the event payload.
Dark host example The same event can feed an overlay on darker editorial surfaces.
Event log 
Hover an object in either preview to inspect the emitted event detail.
Attributes

HTML configuration surface

Attribute Type Default Notes
speed number 900 Positive number controlling simulated time progression.
label-limit number 14 Positive integer limit for visible labels.
start-time string 2026-01-15T05:00:00.000Z ISO timestamp used as the initial sky state.
dark-mode boolean false Switches the foreground palette for darker host surfaces.
Properties

JavaScript-facing surface

Property Type Reflects Notes
speed number speed Matches the animation speed attribute.
labelLimit number label-limit Controls how many visible labels the banner shows.
startTime string start-time Accepts the initial sky time as an ISO timestamp string.
darkMode boolean dark-mode Enables the higher-contrast palette for dark hosts.
Events

Custom events emitted by the component

Event When it fires Detail shape
starmap-object-selected When the hovered astronomical object changes. { selected, id, name, type, observability, constellation, magnitude, distanceLy, altitude, azimuth }

When detail.selected is false, the rest of the payload fields are null.

The preview overlays above show a recommended host response: listen for starmap-object-selected and write the hovered object detail into a positioned card or caption layer. 

type StarmapSelectionDetail = {
  selected: boolean;
  id: string | null;
  name: string | null;
  type: string | null;
  observability: string | null;
  constellation: string | null;
  magnitude: number | null;
  distanceLy: number | null;
  altitude: number | null;
  azimuth: number | null;
};
Starter Example

Viable first integration

This is the recommended first example for a new site because it shows package import, host-owned layout, configuration attributes, the emitted selection event, and a host-owned overlay that surfaces the hover data. 

import '@briangershon/lumens-starmap-banner';

const banner = document.querySelector('lumens-starmap-banner');
const overlay = document.querySelector('[data-starmap-overlay]');

banner?.addEventListener('starmap-object-selected', (event) => {
  if (!overlay) return;

  if (!event.detail.selected) {
    overlay.textContent = 'Hover a star or unseen object to inspect it.';
    return;
  }

  overlay.textContent = [
    event.detail.name,
    event.detail.type,
    event.detail.constellation,
  ]
    .filter(Boolean)
    .join(' · ');
});
<header class="site-hero">
  <div data-starmap-overlay class="starmap-hover-card">
    Hover a star or unseen object to inspect it.
  </div>
  <lumens-starmap-banner
    dark-mode
    speed="900"
    label-limit="14"
    start-time="2026-01-15T05:00:00Z"
  ></lumens-starmap-banner>
</header>

Recommended pattern: treat the overlay as host UI layered in front of the banner, not as UI owned by the custom element itself.

Behavior Notes

What to expect in a host page

Host-owned layout

The banner is intended to layer into a host header rather than take over the full page.

Light and dark surfaces

Use the default palette for light hosts or add dark-mode on darker surfaces.

Hover-driven detail

Host interfaces can react to the hover event to show supporting copy, labels, or analytics.