hb-site-slideshow (site-slideshow)

Category: content
Tags: content, media
Layout: fullscreen (metadata)
Package: @htmlbricks/hb-site-slideshow

Overview

hb-site-slideshow is a full-viewport image slideshow. You supply a list of slides as JSON: each slide has an image URL (href) and an optional caption. Optional props control the starting slide and autoplay. The default UI includes previous/next controls, a dot strip, and a caption bar when the active slide has a caption. You can replace pieces of that UI with slots, tune appearance with Bulma CSS variables, and listen for slide and hover events from the host page.

Custom element

<hb-site-slideshow …></hb-site-slideshow>

Data model

Each slide is an object with:

| Field | Type | Required | Description | | --- | --- | --- | --- | | href | string | yes | Image URL. Slides without href are dropped. | | caption | string | no | If set on the active slide, a caption bar is shown at the bottom. | | index | number | no | Logical slide index; if omitted, slides are numbered 0 … n-1 in array order. |

The data prop is always an array of these objects (see Attributes).

Attributes

Web component attributes are strings. Use snake_case names where the runtime maps them to component props.

| Attribute | Required | Description | | --- | --- | --- | | data | yes | JSON string: array of slide objects (href, optional caption, optional index). | | index | no | Initial slide index as a decimal string (e.g. "0", "2"). Out-of-range or invalid values fall back to 0. | | timer | no | Autoplay interval in milliseconds, as a string (e.g. "3000"). If omitted or empty, there is no autoplay. Values below 100 are clamped to 100. While the pointer is over the main slideshow area, autoplay does not advance slides. | | id | no | Passed through for host use (string). |

The TypeScript Component type also lists optional style; the current implementation does not wire style in the component script, so prefer styling via CSS variables and host layout rather than a style attribute unless your build layer adds it.

Boolean and number conventions

For this element, numbers (index, timer) are passed as their string form in HTML. There are no boolean attributes on this tag.

Behavior

• Rendering: If data parses to an empty list (or no valid slides), the component shows the text: no image provided as data.
• Navigation: Previous/next wrap at the ends of the list. Clicking a dot jumps to that slide. Changing the slide dispatches changeSlide.
• Autoplay: When timer is set, slides advance on an interval. Autoplay is suspended while mouseentered is true on the slideshow container.
• Overlay slot: If you provide the overlay slot, hovering still toggles mouseentered. When hovered and the overlay slot exists, the default slideshow UI is hidden and the overlay slot is shown instead. Leaving the overlay dispatches changeHover with hover: false.
• Captions and dots: If any slide has a caption, the dot strip is offset upward to leave room for the caption bar (only the active slide’s caption is shown).

Events

Listen with addEventListener or your framework’s binding. Event names are camelCase as emitted.

| Event | detail | When | | --- | --- | --- | | changeSlide | { index: number } | Active slide index changed (controls, dots, or autoplay). | | changeHover | { index: number; hover: boolean } | Pointer entered or left the main slideshow container (hover: true / false). When using the overlay slot, leaving the overlay also emits changeHover with hover: false. |

Styling (Bulma)

The component uses Bulma CSS variables on :host for arrows, dots, caption chrome, and spacing. See the Bulma CSS variables documentation.

Common CSS custom properties

| Variable | Role | | --- | --- | | --bulma-white | Previous/next chevrons and caption text on the dimmed bar. | | --bulma-border | Fill for inactive slide dots. | | --bulma-text-strong | Active and hovered dot fill. | | --bulma-block-spacing | Dot strip offset and caption bar rhythm. | | --bulma-scheme-invert | Caption bar tint and arrow hover wash. | | --bulma-radius-small | Corner radius for arrow controls. |

Set these from the light DOM on hb-site-slideshow (or ancestors), depending on how your app scopes custom properties.

CSS parts

| Part | Description | | --- | --- | | dot | One slide indicator; the current slide has class is-active. | | caption_container | Full-width bar at the bottom when the current slide has a caption. | | caption_content | Centered caption text inside the bar. | | cover_on_images | Layer above the slide images (z-index above images). Default slot content for cover_on_images is rendered here. | | dots | Wrapper around the dot strip; the dots slot replaces the default generated dots. |

Example (host stylesheet):

hb-site-slideshow::part(dot) {
  /* custom dot sizing, etc. */
}

Slots

| Slot | Description | | --- | --- | | overlay | When this slot has content, hovering shows this full-screen layer instead of the default slideshow UI. | | prev | Previous control; default is a text chevron (❮). | | next | Next control; default is a text chevron (❯). | | dots | Custom indicators; default renders one part="dot" element per slide. | | cover_on_images | Optional markup layered above images inside part="cover_on_images". |

Examples

Minimal usage

<hb-site-slideshow
  data='[{"href":"https://example.com/a.jpg","caption":"First"},{"href":"https://example.com/b.jpg"}]'
  index="0"
></hb-site-slideshow>

Autoplay every 6 seconds

<hb-site-slideshow
  data='[{"href":"https://example.com/1.jpg"},{"href":"https://example.com/2.jpg","caption":"Slide 2"}]'
  index="0"
  timer="6000"
></hb-site-slideshow>

Listening for slide changes (vanilla JS)

<hb-site-slideshow
  id="hero"
  data='[{"href":"https://example.com/hero.jpg","caption":"Welcome"}]'
></hb-site-slideshow>
<script>
  document.getElementById("hero").addEventListener("changeSlide", (e) => {
    console.log("slide", e.detail.index);
  });
</script>

License

Package metadata references Apache-2.0 (see LICENSE.md in the published package when consuming from npm).