Barebone base for building Hypermedia-driven applications


UI-agnostic base element which can be used to build hypermedia-driven single page applications.

Implemented using lit-element


yarn add @hydrofoil/hydrofoil-shell



The core element, which manages a state (single resource representation).

This element is abstract. It does not:

  • handle of client-server interaction (doesn't load the resource)
  • does not render any shell UI
  • delegates the rending of resource representations to <lit-view> element

Using the element

In order to actually deploy a shell element simple steps are required:

  1. inherit from the base
  2. implement loadResourceInternal
  3. override renderMain to create some core app UI

Here's an example of how this would be done

import HydrofoilShell from '@hydrofoil-shell/hydrofoil-shell/hydrofoil-shell'
import {customElement, html} from 'lit-element'

export default class MyAppShell extends HydrofoilShell {
  renderMain () {
    // call base to keep using <lit-view> to render the actual resource
    return html`
      <nav>Some static menu</nav>
      <section class=main>
      <footer>Footer element</footer>

  loadResourceInternal (uri) {
    return fetch(uri)

The base shell element does not implement the actual loading so that it's not being coupled with a single client library or API implementation. Still, instead of repeating the load method every time you should build a hydrofoil application, a mixin can be used instead to reuse the logic for loading the resources.

For example, Hydra APIs can be consumed by mixing in alcaeus-loader

+import AlcaeusLoader from '@hydrofoil-shell/alcaeus-loader`

-export default class MyAppShell extends HydrofoilShell {
+export default class MyAppShell extends AlcaeusLoader(HydrofoilShell) {

-  loadResourceInternal (uri) {
-    return fetch(uri)
-  }


A helper element, which helps manage multiple resource. Just as the base shell element, it only serves as a skeleton and needs to be inherited to actually serve as a presentation layer.

For examples check out the material design implementations hydrofoil-resource-tabs and hydrofoil-resource-accordion.


The element is controlled by standard DOM events. To add a resource to the ones displayed dispatch hydrofoil-append-resource from any child element.

child.dispatchEvent(new CustomEvent('hydrofoil-append-resource', {
  bubbles: true,
  composed: true,
  detail: {
    parent: currentResource,
    resource: nextResource,

Both parent and resource are mandatory. If parent is not the topmost resource on the stack all its current children will be replaced with nextResource.

To remove an element from the stack, dispatch hydrofoil-close-resource. This will also remove any other resources higher on the stack.

child.dispatchEvent(new CustomEvent('hydrofoil-append-resource', {
  bubbles: true,
  composed: true,
  detail: {
    resource: removedResource,

| Before | event | After | Note | | -- | -- | -- | -- | | 1. resA | hydrofoil-append-resource
- parent: resA
- resource: resB | 1. resA
2. resB | Add resB to stack | | 1. resA
2. resB | hydrofoil-append-resource
- parent: resA
- resource: resC | 1. resA
2. resC | Replace resB with resC | | 1. resA
2. resC | hydrofoil-append-resource
- parent: resC
- resource: resD | 1. resA
2. resC
3. resD | Further append resD | 1. resA
2. resC
3. resD | hydrofoil-close-resource
- resource: resC | 1. resA | Remove resC which also discards resD |


Link to this version
ImportedReleased 08 May 2019MIT License
Framework Support
Browser Independent
Install with
npm install @hydrofoil/hydrofoil-shell"@0.2.0"
Run the above npm command in your project folder. If you have any issues installing, please contact the author.
Release notes - Version 0.2.0


  • @babel/core#^7.4.4
  • @babel/preset-env#^7.4.4
  • @lit-any/lit-any#^0.8.1
  • ld-navigation#^0.5.2
  • lit-element#^2.0.0