Interface StorymapOptions

Public data and options types for constructing a StoryMap.

The data types are exported rather than only referenced: they are what a host actually types its document and options with, and TypeDoc warns about a documented member whose type it cannot link.

interface StorymapOptions {
    api_key_flickr: string;
    attribution: string;
    autoplay: number;
    autoplay_media: boolean;
    base_class: string;
    basemaps?: StorymapBasemap[];
    calculate_zoom: boolean;
    call_to_action: boolean;
    call_to_action_text: string;
    consent_required: boolean;
    default_bg_color: { b: number; g: number; r: number };
    duration: number;
    ease: unknown;
    font_css: string | false;
    fullscreen: boolean;
    fxmode?: "none" | "slide" | "fade";
    height: number;
    hudbgcolor?: string;
    hudcolor?: string;
    hudopacity?: number;
    iiif: {
        attribution: string;
        fallbackUrl?: string;
        height?: number;
        url: string;
        width?: number;
    };
    keyboard: boolean;
    language: string;
    layout: string;
    line_color: string;
    line_color_inactive: string;
    line_dash: string;
    line_follows_path: boolean;
    line_join: string;
    line_opacity: number;
    line_weight: number;
    map_access_token: string;
    map_area: "full"
    | "left";
    map_as_image: boolean;
    map_background_color: string;
    map_bbox: number[] | null;
    map_center_offset: { left: number; top: number } | null;
    map_height: number;
    map_mini: boolean;
    map_options: StorymapMapOptions;
    map_overview_center: { lat: number; lon: number } | null;
    map_size_sticky: number;
    map_type: string;
    marker_labels: boolean;
    menubar_default_y: number;
    menubar_height: number;
    mode?: "standard" | "static";
    nocache: boolean;
    overlays: StorymapOverlayLayer[];
    overview_extent: [number, number, number, number] | null;
    progressbar?:
        | boolean
        | "bar"
        | "dots"
        | "squares"
        | "block"
        | "thinblock"
        | "off";
    script_path: string;
    see_also?: { id: string; type: string }[];
    show_back_to_start: boolean;
    show_distance: boolean;
    show_headings?: boolean;
    show_history_line: boolean;
    show_info?: boolean;
    show_layers_control: boolean;
    show_lines: boolean;
    show_overview: boolean;
    show_progress: boolean;
    show_scrollbars?: boolean;
    shownav?: boolean;
    skinny_size: number;
    slide_default_fade: string;
    slide_padding_lr: number;
    slideshow?: boolean;
    slideshow_source?: boolean;
    start_at_slide: number;
    storyslider_height: number;
    text_align: "left" | "center" | "right";
    text_background_color: string;
    text_color: string;
    textmode?: "left" | "right" | "bottom";
    textsize?: number;
    theme?: "dark" | "light";
    tile_source_factory: TileSourceFactory | null;
    tilejson?: StorymapTilejson;
    trackResize: boolean;
    use_custom_markers: boolean;
    viewerheight?: string;
    width: number;
    zoomify?:
        | boolean
        | {
            attribution?: string;
            height?: number;
            path?: string;
            tolerance?: number;
            width?: number;
        };
    [key: string]: unknown;
}

Indexable

[key: string]: unknown

Index

Properties

api_key_flickr attribution autoplay autoplay_media base_class basemaps? calculate_zoom call_to_action call_to_action_text consent_required default_bg_color duration ease font_css fullscreen fxmode? height hudbgcolor? hudcolor? hudopacity? iiif keyboard language layout line_color line_color_inactive line_dash line_follows_path line_join line_opacity line_weight map_access_token map_area map_as_image map_background_color map_bbox map_center_offset map_height map_mini map_options map_overview_center map_size_sticky map_type marker_labels menubar_default_y menubar_height mode? nocache overlays overview_extent progressbar? script_path see_also? show_back_to_start show_distance show_headings? show_history_line show_info? show_layers_control show_lines show_overview show_progress show_scrollbars? shownav? skinny_size slide_default_fade slide_padding_lr slideshow? slideshow_source? start_at_slide storyslider_height text_align text_background_color text_color textmode? textsize? theme? tile_source_factory tilejson? trackResize use_custom_markers viewerheight? width zoomify?

Properties

api_key_flickr

api_key_flickr: string

attribution

attribution: string

autoplay

autoplay: number

Advance slides automatically every N milliseconds; 0 disables (issue #380)

autoplay_media

autoplay_media: boolean

With autoplay on, wait for the current slide's audio or video to end before advancing instead of using the autoplay millisecond timer, which stays as the fallback. Slides without playable media keep the timer, so a mixed story never stalls.

base_class

base_class: string

`Optional`basemaps

basemaps?: StorymapBasemap[]

Selectable base maps for the layer switcher. Entry 0 is the initial basemap unless map_type says otherwise; omit for an overlays-only control. Constructor- and runtime-only when labels are functions (functions cannot ride storymap JSON — see label).

calculate_zoom

calculate_zoom: boolean

call_to_action

call_to_action: boolean

call_to_action_text

call_to_action_text: string

consent_required

consent_required: boolean

Ask for permission before loading anything from external services (media embeds, map tiles, external font CSS) — GDPR consent mode. Decisions are remembered per service in localStorage under storymapjs-consent with no expiry: clearing site data is what makes the viewer ask again.

default_bg_color

default_bg_color: { b: number; g: number; r: number }

duration

duration: number

ease

ease: unknown

font_css

font_css: string | false

Font theme stylesheet: stock:<name>, a URL/path, or false for no injected stylesheet (the host bundles the theme itself).

fullscreen

fullscreen: boolean

Show a fullscreen toggle button in the menubar (default: true)

`Optional`fxmode

fxmode?: "none" | "slide" | "fade"

Slide transition effect (slideshow fxmode): "slide" (default) is the current glide, "fade" cross-fades slides, "none" jumps without animation. prefers-reduced-motion still forces "none". Honored only with slideshow_source.

height

height: number

`Optional`hudbgcolor

hudbgcolor?: string

HUD background color override (slideshow hudbgcolor): sets the --vco-hud-bg CSS variable. Absent follows the theme. Honored only with slideshow_source.

`Optional`hudcolor

hudcolor?: string

HUD foreground color override (slideshow hudcolor): sets the --vco-hud-fg CSS variable. Absent follows the theme. Honored only with slideshow_source.

`Optional`hudopacity

hudopacity?: number

HUD opacity percent 0..100 (slideshow hudopacity): applied to the HUD background. Absent means fully opaque theme background. Honored only with slideshow_source.

iiif

iiif: {
    attribution: string;
    fallbackUrl?: string;
    height?: number;
    url: string;
    width?: number;
}

IIIF image service for image maps. url is the info.json; width and height record the canvas size so region clamping and the static fallback work without another fetch; fallbackUrl is a full-size image used when info.json cannot be loaded (slideshow image_static).

keyboard

keyboard: boolean

Navigate slides with arrow keys anywhere on the page (default false: arrows only work when the slide panel has focus). Form elements and the map itself (which pans) are always skipped. Read at construction.

language

language: string

layout

layout: string

line_color

line_color: string

line_color_inactive

line_color_inactive: string

line_dash

line_dash: string

line_follows_path

line_follows_path: boolean

line_join

line_join: string

line_opacity

line_opacity: number

line_weight

line_weight: number

map_access_token

map_access_token: string

map_area

map_area: "full" | "left"

Landscape map layout: "full" (default) spans the whole width with the slide panel fading in over it (the map view is offset so markers clear the panel); "left" limits the map to the left, visible half with an opaque slide panel — no offset needed, fits and constraints align with the visible area directly. Portrait layouts are unaffected.

map_as_image

map_as_image: boolean

map_background_color

map_background_color: string

map_bbox

map_bbox: number[] | null

Limit the map to a bounding box [west, south, east, north] (lon/lat; raw image pixel coordinates for image-space maps). The view center is constrained to the box; null (default) leaves the map unconstrained.

map_center_offset

map_center_offset: { left: number; top: number } | null

map_height

map_height: number

map_mini

map_mini: boolean

map_options

map_options: StorymapMapOptions

Raw OpenLayers map configuration. controls replaces the StoryMapJS defaults, interactions are added to the viewer's own pan/zoom interactions, and view is merged over the computed default view and element (an HTMLElement or DOM id) replaces the auto-created map container div.

map_overview_center

map_overview_center: { lat: number; lon: number } | null

Override the overview fit center (issues #107, #271)

map_size_sticky

map_size_sticky: number

map_type

map_type: string

marker_labels

marker_labels: boolean

menubar_default_y

menubar_default_y: number

menubar_height

menubar_height: number

`Optional`mode

mode?: "standard" | "static"

Reading mode (slideshow mode): "standard" (default) is the slider; "static" stacks all slides in a scrollable list and follows the map to the slide in view. Honored only with slideshow_source.

nocache

nocache: boolean

Re-fetch the source file on every load, bypassing caches (issue #417)

overlays

overlays: StorymapOverlayLayer[]

Stacked raster overlays above the base map, below the route lines. Each entry accepts any map_type value (XYZ template, osm:style, …) plus per-layer presentation; see StorymapOverlayLayer. Empty (default) means base map only.

overview_extent

overview_extent: [number, number, number, number] | null

Constrain the minimap overview to a bounding box [west, south, east, north] in lon/lat (mercator maps only); null (default) leaves the overview unconstrained.

`Optional`progressbar

Progress indicator style (slideshow progressbar): false/"off" hides it (same as show_progress: false), true/"bar" is the classic fill bar, dots/squares render one step per slide, block/thinblock are fill-bar height variants. Absent means the show_progress boolean decides and the style is "bar". Honored only with slideshow_source.

script_path

script_path: string

`Optional`see_also

see_also?: { id: string; type: string }[]

The seeAlso targets a IIIF manifest points at, recorded but not fetched — see loadSeeAlso().

show_back_to_start

show_back_to_start: boolean

Show the back-to-the-beginning button in the menubar (default: true)

show_distance

show_distance: boolean

Show the great-circle route distance in the menubar (issue #341)

`Optional`show_headings

show_headings?: boolean

Render slide headlines (slideshow showheadings). Default true; false hides headline elements via CSS. Honored only with slideshow_source.

show_history_line

show_history_line: boolean

`Optional`show_info

show_info?: boolean

Show media captions and credits (slideshow showinfo). Default true; false hides the caption/credit block. Honored only with slideshow_source.

show_layers_control

show_layers_control: boolean

Show the basemap/overlay switcher in the menubar (default false)

show_lines

show_lines: boolean

show_overview

show_overview: boolean

Show the map overview button in the menubar (default: true)

show_progress

show_progress: boolean

Show a progress bar in the menubar (issue #247)

`Optional`show_scrollbars

show_scrollbars?: boolean

Show scrollbars in the slide panel (slideshow showscrollbars). Default true; false hides them via CSS (content still scrolls). Honored only with slideshow_source.

`Optional`shownav

shownav?: boolean

Show the previous/next slide navigation (slideshow shownav). Default true; false hides the nav chrome (keyboard/AT navigation still works, like show_progress: false keeps the story usable). Honored only with slideshow_source.

skinny_size

skinny_size: number

slide_default_fade

slide_default_fade: string

slide_padding_lr

slide_padding_lr: number

`Optional`slideshow

slideshow?: boolean

Detect slideshow tours automatically (default true): an AnnotationCollection shaped like one loads through the translator. Set false to disable detection (such documents then fail validation as before).

`Optional` `Internal`slideshow_source

slideshow_source?: boolean

Source marker: true when the loaded document came from a slideshow tour (set programmatically by the viewer, never from data). The slideshow-motivated presentation fields (location rotation/filter/mask/basemap, narration/media playback bags, slidetimeout, imgoverlay, and the player-chrome options above) render only with this set — internal documents keep the long-standing behavior. Absent from constructor defaults and schema, so storymap data cannot inject it; it travels via options copies. Hosts may pass it explicitly as an escape hatch.

start_at_slide

start_at_slide: number

storyslider_height

storyslider_height: number

text_align

text_align: "left" | "center" | "right"

Default text alignment for slide text: left, center or right (issue #244)

text_background_color

text_background_color: string

Slide panel background color override (issue #177)

text_color

text_color: string

Slide text color override, sets --vco-color-text (issue #177)

`Optional`textmode

textmode?: "left" | "right" | "bottom"

Slide panel dock (slideshow textmode): which side the text panel occupies in landscape. "right" (default) is the current layout; "left" mirrors it; "bottom" docks the panel below the map. Portrait layouts always behave like "bottom". Honored only with slideshow_source.

`Optional`textsize

textsize?: number

Slide panel size as a percentage (slideshow textsize): percent of the width for side docks, of the height for the bottom dock. Range 10..80; absent keeps the built-in 50/50 split. Honored only with slideshow_source.

`Optional`theme

theme?: "dark" | "light"

Colour theme: "dark" forces the dark palette, "light" pins the light one (overriding an OS dark preference), unset follows prefers-color-scheme. Construction-time only, like map_type.

tile_source_factory

tile_source_factory: TileSourceFactory | null

Custom OpenLayers tile layer/source factory (issue #473): consulted by the tile layer factory before the built-in map_type switch, for every base, overlay and minimap layer. Return a TileLayer (or a bare Source, auto-wrapped in one) for custom handling — e.g. WMS — or null/undefined to fall through to the default types. Constructor- and runtime-only: functions cannot ride storymap JSON.

`Optional`tilejson

tilejson?: StorymapTilejson

trackResize

trackResize: boolean

use_custom_markers

use_custom_markers: boolean

`Optional`viewerheight

viewerheight?: string

Fixed viewer height (slideshow viewerheight), e.g. "400px": applied as a container height override when set. Absent keeps the measured-container behavior. Only px, % and vh units accepted. Honored only with slideshow_source.

width

width: number

`Optional`zoomify

zoomify?:
    | boolean
    | {
        attribution?: string;
        height?: number;
        path?: string;
        tolerance?: number;
        width?: number;
    }

Legacy zoomify image pyramid (map_type: "zoomify"): the tiles are placed at the standard mercator tile positions, stretched from the world's top-left corner.

Interface StorymapOptions

Indexable

Index

Properties

Properties

api_key_flickr

attribution

autoplay

autoplay_media

base_class

Optionalbasemaps

calculate_zoom

call_to_action

call_to_action_text

consent_required

default_bg_color

duration

ease

font_css

fullscreen

Optionalfxmode

height

Optionalhudbgcolor

Optionalhudcolor

Optionalhudopacity

iiif

keyboard

language

layout

line_color

line_color_inactive

line_dash

line_follows_path

line_join

line_opacity

line_weight

map_access_token

map_area

map_as_image

map_background_color

map_bbox

map_center_offset

map_height

map_mini

map_options

map_overview_center

map_size_sticky

map_type

marker_labels

menubar_default_y

menubar_height

Optionalmode

nocache

overlays

overview_extent

Optionalprogressbar

script_path

Optionalsee_also

show_back_to_start

show_distance

Optionalshow_headings

show_history_line

Optionalshow_info

show_layers_control

show_lines

show_overview

show_progress

Optionalshow_scrollbars

Optionalshownav

skinny_size

slide_default_fade

slide_padding_lr

Optionalslideshow

Optional Internalslideshow_source

start_at_slide

storyslider_height

text_align

text_background_color

text_color

Optionaltextmode

`Optional`basemaps

`Optional`fxmode

`Optional`hudbgcolor

`Optional`hudcolor

`Optional`hudopacity

`Optional`mode

`Optional`progressbar

`Optional`see_also

`Optional`show_headings

`Optional`show_info

`Optional`show_scrollbars

`Optional`shownav

`Optional`slideshow

`Optional` `Internal`slideshow_source

`Optional`textmode

`Optional`textsize

`Optional`theme

`Optional`tilejson

`Optional`viewerheight

`Optional`zoomify