{"id":50320662,"url":"https://github.com/CogappLabs/StoriiiesViewer","last_synced_at":"2026-06-14T18:00:39.243Z","repository":{"id":205316236,"uuid":"665501791","full_name":"CogappLabs/StoriiiesViewer","owner":"CogappLabs","description":"An open source online storytelling platform for everyone. Built by Cogapp.","archived":false,"fork":false,"pushed_at":"2026-02-16T11:29:57.000Z","size":12685,"stargazers_count":40,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-16T19:59:26.637Z","etag":null,"topics":["cogapp","iiif","musetech","storytelling"],"latest_commit_sha":null,"homepage":"https://www.cogapp.com/storiiies","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CogappLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-12T10:47:27.000Z","updated_at":"2026-02-16T11:23:45.000Z","dependencies_parsed_at":"2025-12-03T01:04:57.774Z","dependency_job_id":null,"html_url":"https://github.com/CogappLabs/StoriiiesViewer","commit_stats":null,"previous_names":["cogapplabs/storiiiesviewer"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/CogappLabs/StoriiiesViewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogappLabs%2FStoriiiesViewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogappLabs%2FStoriiiesViewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogappLabs%2FStoriiiesViewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogappLabs%2FStoriiiesViewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CogappLabs","download_url":"https://codeload.github.com/CogappLabs/StoriiiesViewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogappLabs%2FStoriiiesViewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34331812,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cogapp","iiif","musetech","storytelling"],"created_at":"2026-05-29T03:04:51.015Z","updated_at":"2026-06-14T18:00:39.238Z","avatar_url":"https://github.com/CogappLabs.png","language":"TypeScript","funding_links":[],"categories":["Interactive Content"],"sub_categories":[],"readme":"# Storiiies Viewer ![Build status badge](https://github.com/CogappLabs/StoriiiesViewer/actions/workflows/build.yml/badge.svg)\n\n![Storiies promotional banner](docs/Storiies_banner_1280_95.jpg)\n\nStoriiies Viewer is an open source viewer for [Storiiies](https://www.cogapp.com/r-d/storiiies), the IIIF digital storytelling platform.\n\n## Demo\n\n[See an example StoriiiesViewer in action on codepen](https://codepen.io/Cogapp/pen/JjxbjGz)\n\n## Usage\n\n[API documentation](https://cogapplabs.github.io/StoriiiesViewer/api)\n\n### Adding the dependencies\n\nThere are two options for adding StoriiiesViewer to your project:\n\n#### In the browser\n\n(This is the quickest and easiest way to get started)\n\nYou can include the JavaScript and CSS in the HTML like so, using the [unpkg CDN](https://unpkg.com/):\n\n```HTML\n\u003chead\u003e\n  \u003c!-- ... --\u003e\n  \u003clink rel=\"stylesheet\" href=\"https://unpkg.com/@cogapp/storiiies-viewer@latest/dist/storiiies-viewer.css\"\u003e\n  \u003cscript src=\"https://unpkg.com/@cogapp/storiiies-viewer@latest/dist/umd/storiiies-viewer.js\"\u003e\u003c/script\u003e\n  \u003c!-- ... --\u003e\n\u003c/head\u003e\n```\n\nOr you could save these files and serve them locally if you prefer.\n\nIncluding the JavaScript file this way will make `StoriiiesViewer` available globally in JavaScript.\n\n#### Using a bundler\n\n1. Install the dependecy with `npm install @cogapp/storiiies-viewer`\n2. Use `import StoriiiesViewer from '@cogapp/storiiies-viewer'` in your code to access the StoriiiesViewer constructor\n3. Depending on how your tooling handles importing CSS you might also be able to import the CSS file with `import @cogapp/storiiies-viewer/dist/storiiies-viewer.css` — but you could also use the method above, or copy the contents of the CSS file into your own src files.\n\n### Initialise a viewer\n\nIn your HTML:\n\n```HTML\n\u003cdiv id=\"storiiies-viewer\"\u003e\u003c/div\u003e\n```\n\nIn your JavaScript\n\n```JS\ndocument.addEventListener('DOMContentLoaded', () =\u003e {\n  const myViewer = new StoriiiesViewer({\n    container: \"#storiiies-viewer\", // or document.querySelector(\"#storiiies-viewer\")\n    manifestUrl: \"https://path-to-your-storiiies-manifest\",\n  });\n});\n```\n\n## Customisation\n\nTo customise of appearance of StoriiiesViewer you have a few options:\n\n1. If you'd prefer to bring all your own styles, StoriiiesViewer can be styled from scratch without needing to include the default stylesheet\n2. To 'theme' StoriiiesViewer, you may find the custom properties provided by the default stylesheet to be sufficient\n3. Start with default stylesheet and expand or override these styles as you see fit\n\n### Disabling Mouse Navigation\n\nIf you want to disable interactions such as panning and zooming via scroll, you can pass the `disablePanAndZoom` option when initializing the viewer:\n\n```js\ndocument.addEventListener(\"DOMContentLoaded\", () =\u003e {\n  const myViewer = new StoriiiesViewer({\n    container: \"#storiiies-viewer\",\n    manifestUrl: \"https://path-to-your-storiiies-manifest\",\n    disablePanAndZoom: true, // Disables mouse navigation\n  });\n});\n```\n\n### Using a custom \"point of interest\" SVG\n\nYou may provide a custom SVG graphic to use with points of interest.\n\n```js\ndocument.addEventListener(\"DOMContentLoaded\", () =\u003e {\n  const myViewer = new StoriiiesViewer({\n    container: \"#storiiies-viewer\",\n    manifestUrl: \"https://path-to-your-storiiies-manifest\",\n    pointOfInterestSvgUrl: 'https://path-to-your-svg'\n  });\n});\n```\n\nThis overrides the default graphic from StoriiiesViewer. This SVG will be sanitized before it's inserted, and we have a permissive but possibly not exhaustive list of tags and attributes which are allowed.\n\nThe default colour and highlighting on activation and hover of points of interest are controlled by a CSS custom property applied to the `color` rule. If you'd like your custom graphic to use this colourisation then you can use `currentColor` on the parts of the graphic that should adopt this.\n\n## Supported manifest formats\n\nStoriiiesViewer supports a subset of the [IIIF presentation API v3](https://iiif.io/api/presentation/3.0/). Specifically, we target `annotationPages` which are included directly in the manifest ([like in this cookbook recipe](https://iiif.io/api/cookbook/recipe/0258-tagging-external-resource/)).\n\nText based annotations can either be `text/plain` or `text/html` denoted by the `format` field. For `text/plain` newline characters will be converted and output as `\u003cbr\u003e` tags.\n\nSupport for audio exists, and StoriiiesViewer will render an `\u003caudio /\u003e` element for annotations that have a type of `Sound`, and which are structured [like shown in this cookbook recipe](https://iiif.io/api/cookbook/recipe/0002-mvm-audio/).\n\nPoints of interest (markers that target a single point, rather than a region), can be rendered by using a `target` with a type of `specificResource` and a `selector` of `type: \"pointSelector\"`. See this [cookbook recipe for an example]](https://iiif.io/api/cookbook/recipe/0135-annotating-point-in-canvas/).\n\nStoriiiesViewer has no required fields (aside from those required by the presentation API), but it will render certain values from the manifest if provided. These are:\n\n- [A manifest `label`](https://iiif.io/api/presentation/3.0/#label), which is required by the presentation API and will be shown on a \"title slide\", before any annotations\n- [A manifest level `summary`](https://iiif.io/api/presentation/3.0/#summary), which will appear below the label if provided\n- [A manifest level `requiredStatement`](https://iiif.io/api/presentation/3.0/#requiredstatement), which will appear below the summary if provided\n\n\u003e [!NOTE]\u003cbr\u003e\n\u003e Certain features which aren't currently supported include:\n\u003e\n\u003e - Externally referenced `annotationPages` ([as shown in this cookbook recipe](https://iiif.io/api/cookbook/recipe/0306-linking-annotations-to-manifests/))\n\u003e - Multiple images\n\u003e - Full multi-lingual support\n\u003e\n\u003e However, pathways exist to enable these features with further development.\n\n\u003e [!WARNING]\u003cbr\u003e\n\u003e Manifest with a version lower than 3 may load images, but aren't guaranteed to work beyond this, and will display a warning in the console.\n\n### Compatibility with Storiiies Editor\n\nCogapp maintains a free-to-use editor for Storiiies at [storiiies-editor.cogapp.com](https://storiiies-editor.cogapp.com/). To use a compatible v3 manifest for your story, append the short alphanumeric code from the \"view and share\" link to a base URL of `https://manifest.storiiies-editor.cogapp.com/v3/`\n\nFor example, for the link \u003chttps://storiiies.cogapp.com/viewer/7e4va/A-Sunday-on-La-Grande-Jatte-1884\u003e use a manifest URL of \u003chttps://manifest.storiiies-editor.cogapp.com/v3/7e4va\u003e\n\n## Local development\n\n### Installation\n\n#### Pre-requisites\n\n- [Node.js / npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)\n\n\u003e [!IMPORTANT]\u003cbr\u003e\n\u003e Although optional, we recommend using [nvm](https://github.com/nvm-sh/nvm) to match the version of Node used in this project before running the install command, or the npm scripts described below.\n\u003e\n\u003e If you encounter problems and aren't using the version of Node shown in the [.nvmrc](.nvmrc) file, you should try aligning your node version to this first. This represents a known compatibility with the code here and our dependencies.\n\n#### Setup\n\nSwitch node version and install the dependencies in the project root with:\n\n```console\nnvm use\nnpm ci\n```\n\n### Compiling and previewing changes\n\n\u003ctable width=\"100%\"\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth width=\"300px\"\u003eCommand\u003c/th\u003e\n      \u003cth width=\"800px\"\u003eAction\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003enpm run dev\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eWatches files in the \u003ca href=\"./src\"\u003e\u003ccode\u003esrc\u003c/code\u003e\u003c/a\u003e directory for changes and serves a preview at \u003ca href=\"https://localhost:43110\"\u003ehttps://localhost:43110\u003c/a\u003e with hot module replacement\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003enpm run build\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eBuilds the package for use in production. See \"\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\" for how this package can be used\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n### Running the tests\n\n\u003ctable width=\"100%\"\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth width=\"300px\"\u003eCommand\u003c/th\u003e\n      \u003cth width=\"800px\"\u003eAction\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003enpm run test:gui\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eWill start the local dev server and run the e2e tests with the interactive GUI\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003enpm run test\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e Starts the dev server as above, but instead runs the tests without the GUI\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003e [!NOTE]\u003cbr\u003e `npm run cypress:gui` and `npm run cypress` will also do the same as the above _without_ starting the dev server, if you already have it running.\n\n### Linting the code\n\n\u003ctable width=\"100%\"\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth width=\"300px\"\u003eCommand\u003c/th\u003e\n      \u003cth width=\"800px\"\u003eAction\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003enpm run lint\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003eWill lint (and fix where possible) all problems in the code\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n### Image credits from banner image\n\nGeorges Seurat. _[A Sunday on La Grande Jatte](https://www.artic.edu/artworks/27992/a-sunday-on-la-grande-jatte-1884)_, 1884-86. The Art Institute of Chicago.\u003cbr\u003e\nVincent van Gogh. _[The Bedroom](https://www.artic.edu/artworks/28560/the-bedroom)_, 1889. The Art Institute of Chicago.\u003cbr\u003e\nRosalba Carriera. _[A Young Lady with a Parrot](https://www.artic.edu/artworks/103887/a-young-lady-with-a-parrot)_, c. 1730. The Art Institute of Chicago.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCogappLabs%2FStoriiiesViewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCogappLabs%2FStoriiiesViewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCogappLabs%2FStoriiiesViewer/lists"}