Renderer Utilities

The renderer provides a set of utilities to build and interact with the form.

Functions

• buildForm
• destroyForm
• getResponse
• removeEmptyAnswersFromResponse

Components

• BaseRenderer
• SmartFormsRenderer (to be deprecated)
• RendererThemeProvider

Hooks

• useBuildForm
• useRendererQueryClient
• QuestionnaireStore state management hooks
• QuestionnaireResponseStore state management properties
• SmartConfigStore state management properties
• TerminologyServerStore state management properties

note

There are other utilities exposed by the renderer but are not intended for direct use, i.e internal UI components and controls which requires advanced setup. These are used in the Smart Forms app for it's re-population mechanism.

If you are interested, refer to the API Reference section.

BuildForm

The buildForm() function is used to build the form. It takes in BuildFormsParams as arguments. If a QuestionnaireResponse is not provided, an empty QuestionnaireResponse is set as the initial QuestionnaireResponse.

Parameter	Type	Description	Required?
questionnaire	FHIR R4.Questionnaire	Questionnaire to be rendered	Required
questionnaireResponse	FHIR R4.QuestionnaireResponse	Pre-populated/draft/loaded QuestionnaireResponse to be rendered	Optional
readOnly	boolean	Applies read-only mode to all items in the form view	Optional
terminologyServerUrl	string	Terminology server url to fetch terminology. If not provided, the default terminology server will be used.	Optional
additionalContext	Record<string, any>	Additional key-value pairs of SDC variables and values to feed into the renderer's FhirPathContext. Likely used for passing in data from a pre-population module. Example: { 'ObsBodyHeight': <Bundle of height observations> }.	Optional
preserveNavigationState	boolean	Whether to preserve the current navigation state (e.g. current page in paged forms, current tab in tabbed forms) when rebuilding the form. This is useful when you want to perform re-population or other updates without losing the user's current position in the form.	Optional
rendererConfigOptions	RendererConfig	Optional renderer styling and behavioural configurations to have fine-grained control over the styling and behaviour of the renderer.	Optional
qItemOverrideComponents	Record<string, ComponentType<QItemOverrideComponentProps>>	Key-value pairs of React component overrides for specific Questionnaire Items via linkId. Example: { 'linkId123': MyCustomComponent }	Optional
sdcUiOverrideComponents	Record<string, ComponentType<SdcUiOverrideComponentProps>>	Key-value pairs of React component overrides for SDC UI Controls, as defined in: https://hl7.org/fhir/extensions/ValueSet-questionnaire-item-control.html. Example: { 'flyover': MyCustomUIComponent }	Optional

DestroyForm

The destroyForm() function is used to clear the form to a clean state. Under the hood, it cleans up the questionnaire and QuestionnaireResponse state management stores.

GetResponse

The getResponse() function is used to get the QuestionnaireResponse at its current state. If no changes have been made to the form, the initial QuestionnaireResponse is returned.

Use this if you are planning to use a button click to get the QuestionnaireResponse.

If you want to get the latest QuestionnaireResponse every time the form is changed, use the QuestionnaireResponseStore updatableResponse hook.

RemoveEmptyAnswersFromResponse

The removeEmptyAnswersFromResponse() function is used to remove empty/hidden answers from a passed QuestionnaireResponse.

This takes into account enableWhen, enableWhenExpression extensions, items without item.answer, empty item.answer arrays and empty strings. This does not remove items that are hidden by the http://hl7.org/fhir/StructureDefinition/questionnaire-hidden extension.

This function is generally used before saving, printing or exporting the QuestionnaireResponse to ensure the response is clean.

Parameter	Type	Description	Required?
questionnaire	FHIR R4.Questionnaire	Source Questionnaire of the provided QuestionnaireResponse	Required
questionnaireResponse	FHIR R4.QuestionnaireResponse	Filled QuestionnaireResponse	Required

BaseRenderer

The BaseRenderer component is the main component that renders the form.

It renders the Questionnaire and QuestionnaireResponse defined in the QuestionnaireStore and QuestionnaireResponseStore state management stores respectively.

buildForm() used be used in your wrapping component or in an event handler to initialise the form before React renders the BaseRenderer.

SmartFormsRenderer

warning

The SmartFormsRenderer component is planned for deprecation in the future. As a replacement, library users should create their own wrapper around BaseRenderer which includes the useBuildForm() hook.

SmartFormsRenderer provides a fast and easy way to get started with the renderer, but there is a trade-off around customisation and future extensibility. Using your own wrapper provides the following benefits:

• Allows you to customise your own @tanstack/react-query query client if needed. A useRendererQueryClient() hook is provided if you want to stick to the default.
• Allows you to customise your own theme using Material UI Theming. A RendererThemeProvider component is provided if you want to stick to the default.
• Allows you to customise your own loading animation.
• In the future if any additional functionalities are exposed via hooks, they can be easily plugged in to your own wrapper.

See here for replacement options.

The SmartFormsRenderer component is a self-initialising wrapper around the BaseRenderer component. If a QuestionnaireResponse is not provided, an empty QuestionnaireResponse is set as the initial QuestionnaireResponse.

Parameter	Type	Description	Required?
questionnaire	FHIR R4.Questionnaire	Questionnaire to be rendered	Required
questionnaireResponse	FHIR R4.QuestionnaireResponse	Pre-populated/draft/loaded QuestionnaireResponse to be rendered	Optional
additionalVariables	Record<string, object>	Additional key-value pairs of SDC variables and values to feed into the renderer's FhirPathContext. Likely used for passing in data from a pre-population module. Example: { 'ObsBodyHeight': <Bundle of height observations> }.	Optional
terminologyServerUrl	string	Terminology server url to fetch terminology. If not provided, the default terminology server will be used.	Optional
fhirClient	FHIRClient	FHIRClient to perform further FHIR calls (This helps you set fhirClient and patient, user, encounter launch contexts)	Optional
readOnly	boolean	Applies read-only mode to all items in the form view	Optional

RendererThemeProvider

The RendererThemeProvider component provides the default renderer theme based on Material UI. It should be wrapped around the BaseRenderer component.

If you want to customise the renderer to use your own theme, refer to the Material UI Theming documentation.

UseBuildForm

The useBuildForm() hook wraps around the buildForm() function and provides self-initialisation of the form via useLayoutEffect.

The reason why useLayoutEffect is used over useEffect is because the form needs to be initialised before React renders the BaseRenderer component.

This is generally the recommended way to initialise the form in your wrapping component. If you want to initialise the form in an event handler, you can use the buildForm() function directly.

UseRendererQueryClient

The useRendererQueryClient() hook provides the default renderer @tanstack/react-query query client to perform API calls i.e. fetching terminology.

Note that the renderer uses @tanstack/react-query version 4.x.x.

If you want to customise the renderer to use your own query client, refer to the TanStack Query v4 documentation.

State Management Hooks

Refer to the Renderer Store Hooks section for more information on the state management hooks provided by the renderer.