hb-site-slideshow-horizontal — integrator guide

Category: content · Tags: content, media · Package: @htmlbricks/hb-site-slideshow-horizontal

Summary

Horizontal slideshow strip that shows a window of image (or video-style) tiles, with previous/next arrows. Slides are data-driven (JSON); there are no light DOM slots.

Behavior

• Accepts a required data payload: an ordered list of slides. Each slide must include a href (image URL). Entries without href are dropped.
• Slides are sorted by optional index (ascending), then renumbered internally from 0.
• The strip shows size tiles at once when you set size as a positive number. If you omit size, the count is derived from the viewport: round(windowInnerWidth / 250) (minimum practical width still comes from the host).
• slide is the starting index into the flattened list (also used as the window offset for the arrows). It can be synced from the outside; string values are coerced with Number(...).
• Previous / next arrows shift that index and wrap across the list so the window is always filled when there are more slides than visible tiles (the implementation may concatenate from the beginning of the list to pad the row).
• type switches between a plain image caption layout (images, default) and a video-style row with a play affordance and optional duration text.

Custom element

<hb-site-slideshow-horizontal></hb-site-slideshow-horizontal>

Tag name: hb-site-slideshow-horizontal

Slide model (data items)

Each object in the data array can include:

| Field | Required | Description | | --- | --- | --- | | href | Yes | Image URL for the tile. | | caption | No | Shown under the play overlay in videos mode, or as an overlay caption in images mode when present. | | index | No | Sort hint before display (lower first). | | externalLink | No | If set, clicking the tile opens this URL in a new tab (_blank). Takes precedence over link and key. | | link | No | If set (and no externalLink), clicking sets window.location.href to this URL. | | key | No | If set (and neither externalLink nor link), clicking dispatches the slideClick custom event with { key }. | | duration | No | In videos mode, optional duration string next to the title (exposed via CSS part video_sub_time). |

If none of externalLink, link, or key is set, the tile is non-interactive (still shows image/caption UI).

Attributes and properties (web component)

Use snake_case names. In HTML, attribute values are strings: pass JSON as a string for data, and numeric fields as their decimal string form.

| Name | Required | Description | | --- | --- | --- | | data | Yes | JSON string: array of slide objects (see above). Invalid JSON logs an error and yields an empty strip (nothing rendered). | | type | No | "images" (default) or "videos". | | slide | No | Current / initial slide index (stringified number). | | size | No | Number of visible tiles per row (stringified integer). When omitted, width-based sizing is used. | | id | No | Passed through for identification (standard host usage). |

The authoring Component type also lists an optional style field; the current shadow implementation does not apply it—prefer styling via CSS custom properties and global layout around the host.

Events

Listen with addEventListener or the equivalent in your framework.

| Event | detail | When | | --- | --- | --- | | slideClick | { key: string } | User activates a slide that defines key and does not use externalLink or link. |

Styling (Bulma tokens)

The component uses Bulma CSS variables on :host for spacing and arrow chrome. See Bulma CSS variables.

Common CSS custom properties

| Variable | Role | | --- | --- | | --bulma-block-spacing | Vertical margin for the strip and horizontal padding on the arrow hit areas. | | --bulma-white | Color of the arrow glyphs on the gradient fades. | | --bulma-scheme-invert | Base for arrow gradient overlays and hover contrast. |

CSS shadow parts

Style from outside the shadow root with ::part(...).

| Part | Role | | --- | --- | | video_sub_title | Title line under the play affordance when type is videos. | | video_sub_time | Duration text beside the title when duration is set. | | caption_content | Caption text for image-style slides (type images). |

Slots

None—content is entirely driven by the data JSON.

Minimal HTML example

<hb-site-slideshow-horizontal
  data='[
    {"href":"https://placehold.co/600x400/111/fff","caption":"One"},
    {"href":"https://placehold.co/600x400/222/fff","caption":"Two"}
  ]'
></hb-site-slideshow-horizontal>

Video-style layout

<hb-site-slideshow-horizontal
  type="videos"
  data='[
    {"href":"https://placehold.co/640x360/000/fff","caption":"Intro","duration":"0:42"}
  ]'
></hb-site-slideshow-horizontal>

Initial index, fixed strip width, and slideClick

<hb-site-slideshow-horizontal
  id="strip"
  slide="1"
  size="5"
  data='[
    {"href":"https://placehold.co/400x300/004d40/fff?text=A"},
    {"href":"https://placehold.co/400x300/1b5e20/fff?text=B","key":"b"},
    {"href":"https://placehold.co/400x300/33691e/fff?text=C"}
  ]'
></hb-site-slideshow-horizontal>

<script>
  document.getElementById("strip").addEventListener("slideClick", (e) => {
    console.log("key:", e.detail.key);
  });
</script>

TypeScript (authoring)

Props and events for wrappers or Storybook align with types/webcomponent.type.d.ts:

• Component: id, data, optional slide, type, size, and optional style (see note above).
• Data: slide item shape.
• Events: slideClick with { key: string }.

Behavior notes

• If data parses to an empty list, or every item lacks href, the component renders nothing (no arrows, no section).
• Negative slide values are supported by the internal windowing logic; extremely negative values are normalized toward the start of the list.
• Tiles use pointer interactions on the host page; ensure slide href values and link targets meet your accessibility and security policies.