FhirQuestionnaireWidget 1.0.16

QuestionnaireRenderer — embeddable FHIR form widget

The right-hand runtime of the FHIR Questionnaire Builder, packaged as a self-contained, embeddable widget. Drop a FHIR R4 Questionnaire into any web page and get a live, fillable form that runs the SDC logic (enableWhen, calculatedExpression, constraints, validation) and returns a valid QuestionnaireResponse — no builder shell, no iframe, no framework.

• In-page & multi-instance — put several forms on one page; each keeps its own answers, calculations and validation state with zero cross-talk.
• Vanilla ES module — no React/Vue/Angular required. Works with any stack.
• Host-driven UI — the widget has no menus; you turn features on through config and drive it through a small public API.

Table of contents

• Install
• Quick start
• Configuration
• Public API
• Events
• Example: custom “Export FHIR R4” button
• Preview modes
• Multiple isolated widgets
• Styling
• Browser support & dependencies

Install

Fastest: CDN (no install, no auth)

Load the widget straight from jsDelivr, pinned to a release tag — nothing to download, no npm, no token:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/sergeymosyakov/fhir-questionnaire-builder@widget-v1.0.3/dist/questionnaire-widget.css">
<script type="module">
  import { QuestionnaireRenderer } from 'https://cdn.jsdelivr.net/gh/sergeymosyakov/fhir-questionnaire-builder@widget-v1.0.3/dist/questionnaire-widget.js';
  // …
</script>

Or the classic global build (window.FhirQuestionnaireWidget):

<script src="https://cdn.jsdelivr.net/gh/sergeymosyakov/fhir-questionnaire-builder@widget-v1.0.3/dist/questionnaire-widget.global.js"></script>

Pin to a specific @widget-v1.0.x tag for stability; jsDelivr caches immutably.

Download the release bundle

Grab the files from the GitHub Releases page and self-host them. Each release contains:

Verify the download with the SHA256SUMS.txt published alongside the assets.

<link rel="stylesheet" href="questionnaire-widget.css">
<script type="module">
  import { QuestionnaireRenderer } from './questionnaire-widget.js';
  // …
</script>

npm (optional, for bundler projects)

If a maintainer has published to npm, bundler users (React / Vite / webpack) can:

npm install @sergeymosyakov/questionnaire-widget

import { QuestionnaireRenderer } from '@sergeymosyakov/questionnaire-widget';
import '@sergeymosyakov/questionnaire-widget/css';

npm publishing uses Trusted Publishing (OIDC from GitHub Actions — no token/secret involved); the CDN and Release above need no install and no auth and remain the primary channels.

Or build it yourself from source:

npm install
npm run build:widget       # → dist/questionnaire-widget.{js,global.js,css}

NuGet (for .NET web apps)

For Blazor, Razor Pages, or MVC apps that want the widget's static JS/CSS assets without touching npm:

dotnet add package FhirQuestionnaireWidget

Reference it from a Razor/HTML page — the assets are served under _content/FhirQuestionnaireWidget/:

<link rel="stylesheet" href="_content/FhirQuestionnaireWidget/questionnaire-widget.css">
<script type="module">
  import { QuestionnaireRenderer } from '/_content/FhirQuestionnaireWidget/questionnaire-widget.js';
  // …
</script>

Same publishing model as npm above — NuGet Trusted Publishing (OIDC from GitHub Actions, no token/secret). It's a static-asset-only package — no C# API surface, just the built widget files.

Quick start

<link rel="stylesheet" href="questionnaire-widget.css">
<div id="form"></div>

<script type="module">
  import { QuestionnaireRenderer } from './questionnaire-widget.js';

  const questionnaire = await (await fetch('my-questionnaire.json')).json();

  const widget = new QuestionnaireRenderer(document.getElementById('form'), {
    questionnaire,
    config: { previewMode: 'patient', validation: true },
  });

  widget.on('response-changed', qr => console.log('answers now:', qr));
</script>

That renders the questionnaire as a patient-facing form with a live PASS/FAIL validation badge.

Configuration

new QuestionnaireRenderer(mountEl, { questionnaire, response?, config? })

config options

Public API

widget.getResponse();          // → current answers as a FHIR QuestionnaireResponse
widget.setResponse(qr);        // load answers from a QuestionnaireResponse
widget.setLanguage('es');      // switch active language ('' = source)
widget.setConfig({ language: 'es' });    // runtime config — only `language` takes effect
widget.populate('Patient/123');            // SDC $populate against config.fhirBaseUrl
widget.structureMapPopulate('Patient/123'); // run the Questionnaire's sourceStructureMap against a fetched resource
widget.on(event, cb);          // subscribe (returns the widget)
widget.off(event, cb);         // unsubscribe
widget.destroy();              // remove the widget and free all listeners

populate()/structureMapPopulate() merge the resulting answers in place and emit info on success or error on failure (see Events) — nothing is shown on the page unless you subscribe.

getResponse() always returns a fresh, valid FHIR R4 QuestionnaireResponse built from the current answers — this is your integration point for saving, submitting, or exporting.

Note: the chrome flags (search, validation, explain, tooltips, navButton) are construction-time — set them in the initial config. setConfig() only applies language at runtime; to change chrome, destroy() and create a new instance.

Events

Subscribe with widget.on(name, cb):

Example: custom “Export FHIR R4” button

The widget deliberately ships no toolbar. To let a user export their answers, add your own button on the host page and call getResponse() — the returned object is a ready-to-save FHIR R4 QuestionnaireResponse:

<div id="form"></div>
<button id="export">Export FHIR R4</button>

<script type="module">
  import { QuestionnaireRenderer } from './questionnaire-widget.js';

  const questionnaire = await (await fetch('my-questionnaire.json')).json();
  const widget = new QuestionnaireRenderer(document.getElementById('form'), {
    questionnaire,
    config: { previewMode: 'patient', validation: true },
  });

  document.getElementById('export').addEventListener('click', () => {
    const qr = widget.getResponse();               // ← ask the widget for answers
    const blob = new Blob([JSON.stringify(qr, null, 2)], { type: 'application/fhir+json' });
    const url = URL.createObjectURL(blob);
    const a = Object.assign(document.createElement('a'), {
      href: url, download: 'questionnaire-response.json',
    });
    a.click();
    URL.revokeObjectURL(url);
  });
</script>

A working version of this button is in the live demo.

Preview modes

config.previewMode picks how the form looks:

• patient — the clean, fillable form a respondent sees.
• preview — the design view with link IDs, prefixes and status badges.
• json — the live QuestionnaireResponse / Questionnaire JSON.

Multiple isolated widgets

Each widget runs on its own event channel and its own answer store, so two forms on the same page never affect each other:

const a = new QuestionnaireRenderer(elA, { questionnaire: qA });
const b = new QuestionnaireRenderer(elB, { questionnaire: qB });
// answering a never touches b

See the live demo for a three-widget page (one per preview mode) over the same questionnaire.

Styling

Link questionnaire-widget.css once. It carries the widget’s design tokens and all preview/control/modal styles, scoped so they don’t leak into your page’s layout (no global body/reset rules). Override the CSS custom properties on a wrapping element to re-theme (e.g. --c-primary, --c-border, --c-surface).

Browser support & dependencies

• Modern evergreen browsers (ES2020 modules).
• The ESM/global bundles include their runtime dependencies (FHIRPath, DOMPurify, marked) — no extra <script> tags needed.
• No network calls unless you set fhirBaseUrl (reference search / $populate) or use terminology expansion.