About this article
This article is intended for technical teams responsible for website integrations and software development.
The magicapp-recommendation component displays a complete clinical recommendation, including associated content such as rationale, evidence summaries, and supporting information. This article describes how to configure and implement the recommendation widget within your website or application.
Looking for general information about sharing MAGICapp content?
See:
Looking for an overview of MAGICapp embeddable widgets?
See Embeddable widgets for website integration (technical documentation) for an overview of MAGICapp's web components and related widget documentation.
Looking for direct API integration guidance?
See API: Using the MAGICapp API (technical documentation) for information about API user accounts, authentication, permissions, and direct API integrations.
Installation
Add the script tag to your page's <head> section:
<script src="https://app.magicapp.org/widget/recommendationComponent.js" type="module"></script>
Basic Usage
HTML Markup
Add the component directly in your HTML:
<magicapp-recommendation
guideline="guideline-short-code"
recommendation="recommendation-id">
</magicapp-recommendation>
JavaScript
Create and append the component dynamically:
const recComponent = document.createElement('magicapp-recommendation');
recComponent.setAttribute('guideline', 'guideline-short-code');
recComponent.setAttribute('recommendation', 'recommendation-id');
document.getElementById('container').appendChild(recComponent);
Component Attributes
| Attribute | Type | Required | Dynamic Updates | Description |
|---|---|---|---|---|
guideline | string | Yes | No | Guideline short code or ID |
recommendation | string | Yes | Yes | Recommendation ID or short code. Using short code loads the latest published version |
lang | string | No | Yes | Force specific locale (e.g., en, es, fr). Overrides browser language settings |
link-back | boolean | No | Yes | Set to "true" to display a link back to the full guideline |
meta | boolean | No | Yes | Set to "true" to show guideline title, version, and section information |
org | boolean | No | Yes | Set to "true" to display organization logo, name, and publish date |
tab | string | No | Yes | Default tab to open on load. Options: key, advice, rationale, sof, da, adaptation |
env | string | No | No | Environment setting. Use "test" for test environment, omit for production |
Attribute Notes
- Guideline & Recommendation IDs: Both must use the same identifier type (either both short codes or both IDs)
- Dynamic Updates: Attributes marked "Yes" can be changed after the component loads and will trigger a re-render
- Boolean Attributes: Use string "true" to enable (e.g., meta="true")
Complete Example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Recommendation Widget Example</title>
<script src="https://app.magicapp.org/widget/recommendationComponent.js" type="module"></script>
</head>
<body>
<h1>Clinical Recommendation</h1>
<!-- Full-featured recommendation display -->
<magicapp-recommendation
guideline="jW0XmL"
recommendation="Lwr3VG"
lang="en"
link-back="true"
meta="true"
org="true"
tab="key">
</magicapp-recommendation>
<!-- Minimal recommendation display -->
<magicapp-recommendation
guideline="jW0XmL"
recommendation="136004">
</magicapp-recommendation>
</body>
</html>
Using with Authentication
For authenticated API access, nest the component inside magicapp-connect:
<script src="https://app.magicapp.org/widget/apiBuilder.js" type="module"></script>
<script src="https://app.magicapp.org/widget/connectServiceComponent.js" type="module"></script>
<script src="https://app.magicapp.org/widget/recommendationComponent.js" type="module"></script>
<magicapp-connect client-id="your-client-id">
<!-- Automatically uses parent's authentication -->
<magicapp-recommendation
guideline="jW0XmL"
recommendation="Lwr3VG"
meta="true"
org="true">
</magicapp-recommendation>
</magicapp-connect>
Tab Options
The tab attribute controls which section is displayed when the component loads:
| Tab Value | Description |
|---|---|
key | Key information (default expanded view) |
advice | Clinical advice and practical information |
rationale | Rationale and explanation for the recommendation |
sof | Summary of findings (evidence tables) |
da | Decision aids |
adaptation | Adaptation guidance (deprecated - merged into "More info") |
Using as an iFrame
You can also embed recommendations using an iframe with URL parameters.
iFrame URL Format
https://app.magicapp.org/widget/recommendation/?gId={GUIDELINE_ID}&recId={REC_ID}&open=1&tab={TAB}&org=1&m=1&lb=1
URL Parameters
| Parameter | Values | Description |
|---|---|---|
gId | string | Guideline short code or ID |
recId | string | Recommendation ID or short code |
open | 1 | Show recommendation expanded with specified tab open |
tab | key, advice, rationale, sof, da | Which tab to display |
org | 1 | Show organization name, logo, and publish date |
m | 1 | Show guideline metadata (title, version, section) |
lb | 1 | Include link back to full guideline |
lang | locale code | Force specific language (e.g., en, es) |
iFrame Examples
The latest published version with a key info tab:
<iframe
src="https://app.magicapp.org/widget/recommendation/?gId=jW0XmL&recId=Lwr3VG&open=1&tab=key&org=1&m=1&lb=1"
width="100%"
height="600"
frameborder="0">
</iframe>
Specific recommendation ID with rationale tab:
<iframe
src="https://app.magicapp.org/widget/recommendation/?gId=jW0XmL&recId=136004&open=1&tab=rationale&org=1&m=1&lb=1"
width="100%"
height="600"
frameborder="0">
</iframe>
Minimal display (no metadata):
<iframe
src="https://app.magicapp.org/widget/recommendation/?gId=jW0XmL&recId=Lwr3VG"
width="100%"
height="400"
frameborder="0">
</iframe>
Dynamic Updates
You can change certain attributes after the component has loaded to update the display:
const rec = document.querySelector('magicapp-recommendation');
// Switch to a different recommendation
rec.setAttribute('recommendation', 'new-rec-id');
// Change the active tab
rec.setAttribute('tab', 'rationale');
// Change language
rec.setAttribute('lang', 'es');
// Toggle metadata display
rec.setAttribute('meta', 'true');
Test Environment
To use the test environment, add the env attribute:
<magicapp-recommendation
guideline="test-guideline"
recommendation="test-rec-id"
env="test">
</magicapp-recommendation>
Or for iFrame:
https://app-test.magicapp.org/widget/recommendation/?gId=testGuideline&recId=testRec
Browser Compatibility
- Chrome/Edge 80+
- Firefox 75+
- Safari 13.1+
- Opera 67+
Requires support for ES6 modules, Custom Elements, and Shadow DOM.
Troubleshooting
Component is not rendering
- Verify the script is loaded with type="module"
- Check that guideline and recommendation IDs are valid
- Open the browser console for error messages
Wrong language displaying
- Set explicit lang attribute to override browser settings
- Ensure the locale code is supported by MAGICapp
Content not updating
- Only attributes marked "Dynamic Updates: Yes" can be changed after load
- Changing guideline requires page reload
Support
- Email: support@magicevidence.org
- Example: https://magicevidence.org/widget-demo
Last updated: 17 November 2026
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article