Deploying with Form renderer
This content is intended for advanced Studio users.
Form renderer is the mechanism through which forms built in Studio reach end users in a live clinical application. This page covers what Form renderer is, how to install it, and how to configure it to load, pre-fill, and save forms.
For framework-specific integration instructions, see the Framework guides section.
What is Form renderer
Form renderer is a Web Components JavaScript library published by Better. It is designed to make integrating Studio forms into any application as smooth as possible. Once installed and configured, Form renderer fetches the active version of a named form from the EHR Server and renders it directly in your application.
Form Renderer supports the latest stable releases of Google Chrome and Mozilla Firefox.
How Form renderer fits into a clinical application
Form renderer sits between your clinical application and the EHR server. Your application is responsible for providing the EHR server URL, credentials, and the name of the form to render. Form renderer handles fetching the form definition, rendering it in the browser, and, where configured, saving the resulting composition back to the EHR server.
Installation
Form renderer is hosted on the Better private npm registry. To install it, you need a JavaScript package manager (npm, yarn, pnpm, or equivalent) and valid credentials for the Better registry.
For credential setup instructions, refer to the Better Hub Access Guide.
Once you have credentials, install the package:
npm install @better/form-renderer
Passing EHR server URL, credentials, and form name
Once installed, rendering a form requires three pieces of information: the EHR server URL, credentials for that server, and the name of the form to render.
Pass these through the form renderer element's context and properties. The exact syntax differs slightly between frameworks. See Framework guides for framework-specific examples.
The general pattern is:
<form-renderer
[baseUrl]="'https://your-ehr-server.example.com'"
[username]="'your-username'"
[password]="'your-password'"
[form]="'your-form-name'">
</form-renderer>
Form renderer will fetch the active version of the named form and render it.
Pre-filling a form from a saved composition
To render a form pre-filled with data from a previously saved composition, pass the composition ID to Form renderer:
<form-renderer
...
[compositionId]="'f8805e7e-0000-1111-222c-74ca6b0a53e9::test::1'">
</form-renderer>
Form renderer fetches the composition from the EHR server and uses its values to pre-fill the corresponding fields in the form.
Pre-filling also requires an EHR ID. Pass it via the formEnvironment property as a variable named ehrId.
Saving a composition from Form renderer
Form renderer supports two approaches to saving a composition.
Automatic saving via dependency. If your form includes a save or save-incomplete dependency, Form renderer handles saving automatically when the user triggers the action. The onCompositionSaved event is emitted on success, returning a SaveCompositionResponse object.
Programmatic saving via Script API. If your form does not include a save dependency, you can trigger saving programmatically using the saveComposition() method via the renderer's Script API:
const response = await formRendererElement.getScriptApi().saveComposition();
if (!response.success) {
throw response.error;
}
The saveComposition() method accepts an optional validate argument. If set to true (or omitted, as it defaults to true), the form is validated before saving.
Saving a composition requires a valid EHR ID passed via formEnvironment. Saving also commits any Generic Canvas images to the multimedia server before saving the composition, which may take additional time if images are large.
Offline mode
Form renderer supports an offline operating mode for clinical deployments where network connectivity cannot be guaranteed, for example point-of-care environments, field clinics, or applications that must continue functioning during intermittent outages.
In offline mode, Form renderer stops making direct HTTP calls to the EHR server. Instead, it delegates all resource requests like form definitions, API and variable resources, composition data, and composition saving to the host application via a request handler function that you register. The host application is responsible for serving those resources from a local cache (such as IndexedDB), managing synchronisation with the EHR server when connectivity is restored, and handling attachment storage.
Form renderer is storage-agnostic: It renders forms and manages in-memory form state, but it does not persist data itself. All data ownership and offline storage decisions belong to the host application.
Offline mode is available from Form renderer version 3.15.0.
npm install @better/form-renderer
Do not use @latest — it will not resolve to the offline-capable build.
For full implementation details, including the request handler contract, per-framework integration examples, attachment handling, host application responsibilities, and common pitfalls see Offline mode in the Advanced Studio section.
Frequently asked questions (FAQs)
What is Form renderer?
Form renderer is a Web Components JavaScript library published by Better. It allows you to embed and render forms created in Studio inside any clinical application. It fetches the active form from the EHR server and renders it in your application.
How do I install Form renderer?
Install it from the Better private npm registry: npm install @better/form-renderer. You need valid credentials for the Better registry. See the Better Hub Access Guide for credential setup instructions.
What is the minimum configuration needed to render a form?
You need the EHR server URL, credentials, and the form name. Form renderer will fetch the active version of the named form and render it.
Which browsers does Form renderer support?
Form renderer supports the latest stable releases of Google Chrome and Mozilla Firefox.
How do I pre-fill a form with data from a previously saved composition?
Pass the composition ID as the compositionId property on the form-renderer element. Form renderer fetches the composition and uses its values to pre-fill the corresponding fields. An EHR ID must also be provided via formEnvironment.
How do I save a composition from Form renderer?
If your form includes a save or save-incomplete dependency, saving is handled automatically. Otherwise, use the saveComposition() method via the renderer's Script API. The method accepts an optional validate argument (defaults to true) and returns a SaveCompositionResponse promise.
How do I use a summary in Form renderer?
A summary is a form type created in Form builder that displays read-only data from the EHR server. You render a summary in Form renderer the same way as a standard form: Pass the summary's name as the form name. The summary fetches and displays the data defined by its AQL queries at render time.
Does Form renderer work with Angular, React, and Vue?
Yes. Form renderer provides dedicated integration guides for Angular, React, Vue, and framework-agnostic applications. See Framework guides for setup instructions for each.
What is offline mode in Form renderer?
Offline mode is an operating mode in which Form renderer delegates all resource requests — form definitions, data, and composition saving — to the host application via a request handler function, rather than making direct calls to the EHR server. It is designed for clinical deployments where network connectivity cannot be guaranteed. For full implementation details, see Offline mode in the Advanced Studio section.