Skip to content
A custom element that lets you load HTML partials into your Web page. Declarative way for client-side includes.
HTML JavaScript
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update Jun 11, 2018
test Remove whitespace from div wrapper in tests Feb 22, 2018
.gitignore remove .bowerrc (use polyserve) Jun 3, 2016
.travis.yml Update travis dist to xenial Mar 29, 2020 Add Feb 20, 2018
Gruntfile.js Add grunt-bump task Oct 8, 2015
LICENSE fix the license holder (… May 24, 2016 Problem: document._currentScript was only needed in IE11, but Starcou… Feb 13, 2018
bower.json 4.0.1 Mar 11, 2020
index.html Fix and format examples Jan 20, 2016
juicy-html.html 4.0.1 Mar 11, 2020
package.json 4.0.1 Mar 11, 2020
wct.conf.json Always use mocked ajax to shorten delay times Feb 21, 2018

<juicy-html> Build Status

Declarative way for client-side includes

<juicy-html> is a custom element that lets you load HTML partials from JS objects and external files into your DOM. It acts more or less, as include statement known in many other languages. It also provides a simple data binding, that works for native JS/HTML as well as for Polymer's dom-bind.

External files

To load HTML from external file all you need is:

<juicy-html href="./path/to/file.html"></juicy-html>

Markup provided by attribute

<juicy-html html="<h1>Hello World</h1>"></juicy-html>

Data Binding

juicy-html may forward given model object to stamped elements.

    All those nodes will get <code>.model</code> property
    with the reference to the object given in model attribute.
      <template is="dom-bind">
        <p>which can be used by <span>{{model.polymer}}</span></p>
    <custom-element>that uses `.model` property<custom-element>
      // script that may use
      alert( document.currentScript.model );
    "polymer": "Polymer&apos;s dom-bind",
    "vanilla": "as well as by native JS <code>&amp;lt;script&amp;gt;</code> or custom elements"

HTML may naturally be provided from external file, and model can be provided using Polymer's/or any other data-binding as real object (not a string)


Live examples


juicy-html provides a way to extend native <template>'s feature to be able to load content from outside (external file, data server, etc.).

It was started as an addition to Polymer's template binding, as there is no built-in way to insert a <template>'s model variable as HTML (Polymer inserts every string as plain text), AngularJS has a way to do it (ngBindHtml) so we found it convenient to do so in Polymer.

Currently it plain JavaScript, library agnostic custom element, that should work fine with any kind of binding, or none - as simple way to include HTML content from outside.


Your HTML partials can contain:

  • regular HTML
  • inline scripts using <script>//JS code here</script>
  • inline styles using <style>/*CSS code here*/</style>
  • external stylesheets using <link rel="stylesheet" href="path/to/file.css">, with href value relative to the document
  • external scripts using <script src="path/relative/to/main/document.js"></script>

Of course, the 2-way data binding attached within your partials will work as desired.

Please note, that loaded <script> and <style> will be executed every time HTML content is stamped to your document.


  1. Import Web Components' polyfill (if needed):

    <script src="bower_components/webcomponentsjs/webcomponents-lite.js"></script>
  2. Import Custom Element:

    <link rel="import" href="bower_components/juicy-html/juicy-html.html">
  3. Start using it!

    Load HTML partial from a string:

    <juicy-html html="<b>some</b> HTML"></juicy-html>
    <!-- Or <juicy-html html="{{var}}"></juicy-html> where {{ var }} equals "<b>some</b> HTML" -->

    Load HTML partial from a URL:

    <juicy-html href="./path/to/file.html"></juicy-html>
    <!-- Or <juicy-html href="{{var}}"></juicy-html>
         where {{var}} equals "./path/to/file.html", a path relative to the document that must start with / or ./ -->


Attribute Options Default Description
html String "" Safe HTML code to be stamped. Setting this one will skip any pending request for href and remove href attribute.
href String "" Path of a partial to be loaded. Setting this one will remove html attribute.
model(optional) Object/String undefined Object (or JSON.stringify'ied Object) to be attached to every root node of loaded document


Property Type Default Description
model Object undefined See attributes, plays nice with Polymer data-binding
html String "" See attributes
href String "" See attributes
pending XMLHttpRequest pending XHR if any
stampedNodes Array [] Array of stamped nodes.

Please note, that properties are available after element is upgraded. To provide a state before element is upgraded, please use attributes.


Name details Description
stamped Array of Node s Trigger every time content is (re-)stamped, with array of stamped nodes in event.detail


Name Description
skipStampingPendingFile Call to disregard currently pending request


<juicy-html> is framework agnostic custom element, so all you need is Web Components support. However, it plays really nice with Polymer Auto-binding templates, or any other binding library, that sets HTML elements' properties and/or attributes. Check our demos and examples.

Browser compatibility

Name Support Comments
Chrome 48 yes
Firefox 43 yes
Edge 25 yes
Safari 10-11 yes
Safari 9- not tested


  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -m 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :D


For detailed changelog, check Releases.



You can’t perform that action at this time.