SHLinker helps web applications work with SMART Health Links and display them consistently. It provides functions to parse, retrieve, and render SHLinks, making it easy to integrate SHLink functionality into your projects.
- Parse SHLinks and extract relevant information
- Retrieve files associated with SHLinks
- Render SHLink widgets with customizable options
- Decrypt and handle different file types (FHIR, SMART Health Cards)
- TypeScript support for enhanced developer experience
If you don't want to use a build process, you can always download or link to our CSS and JavaScript files:
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>SHLinker Test</title>
</head>
<body>
<div id="main"></div>
<script type="module">
import * as shlink from "https://cdn.jsdelivr.net/npm/[email protected]/dist/shlinker.js";
// ^^ Or download and use a local copy
// pass a shl directly, or let the library parse it from window.location
const parsed = await shlink.parse("https://joshuamandel.com/cgm/#shlink:/eyJ1cmwiOiJodHRwczovL2pvc2h1YW1hbmRlbC5jb20vY2dtL3NobC8xMjBkYXlfYWdwX2J1bmRsZV91bmd1ZXNzYWJsZV9zaGxfaWQwMDAwMDAwIiwiZmxhZyI6IkxVIiwia2V5IjoiYWdwX29ic191bmd1ZXNzYWJsZV9yYW5kb21fa2V5MDAwMDAwMDAwMDAwMCIsImxhYmVsIjoiSm9zaCdzIENHTSBEYXRhIn0");
const retrieved = await shlink.retrieve(parsed)
const main = document.getElementById("main")
shlink.render(retrieved, main, { showDetails: true })
</script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/shlinker.css" />
<!-- ^^ Or download and use a local copy --/>
</body>
</html>If you're using a build process, install the library using npm or its ilk:
npm install shlinkeror
bun install shlinkerImport the library and use its functions:
import { parse, retrieve, render } from 'shlinker';
// Parse an SHLink
const shlinkData = parse('shlink:/...');
// Retrieve files associated with the SHLink
const retrievedData = await retrieve(shlinkData, { recipient: 'John Doe' });
// Render the SHLink widget
const container = document.getElementById('shlink-container');
render(retrievedData, container, { showDetails: true });Parses an SHLink and extracts relevant information.
shlink(optional): The SHLink to parse. If not provided, the current page URL will be used.
Returns an SHLinkData object containing the parsed information.
Retrieves files associated with an SHLink.
shlinkData: The parsed SHLink data obtained fromparse().options(optional): Additional options for file retrieval.recipient(optional): The recipient of the SHLink.passcode(optional): The passcode required to access the SHLink files.
Returns a promise that resolves to an updated SHLinkData object with the retrieved files.
Renders the SHLink widget using the provided SHLink data.
shlinkData: The parsed SHLink data obtained fromparse()orretrieve().container: The DOM element where the SHLink widget will be rendered.config(optional): Configuration options for rendering the SHLink widget.showDetails(optional): Determines whether to show additional details in the widget. Default istrue.showButtons(optional): Array of buttons to show in the widget. Can includecopy,download,share, andqr. If not specified, all buttons are shown.viewerPrefix(optional): The prefix to use when generating the SHLink URL for viewing.qrStartsOpen(optional): Set totrueto display the QR code initially. Default isfalse.logoOverride(optional): URL to override the default SMART logo. Set tonullto remove the logo.logoBottom(optional): URL to add a logo at the bottom of the widget. Set tonullto remove the bottom logo.
The render() function accepts a RenderConfig object that allows you to customize the rendering of the SHLink widget.
showDetails(optional): Set totrueto display additional details such as label, file count, and total size. Default istrue.showButtons(optional): Array of buttons to show in the widget. Can includecopy,download,share, andqr. If not specified, all buttons are shown.viewerPrefix(optional): Specify a custom prefix to use when rendering the SHLink URL for copy-to-clipboard or QR display. Default is the original prefix from the parsed SHLink. Passnullto explicitly strip any prefix from the link.qrStartsOpen(optional): Set totrueto display the QR code initially. Default isfalse.logoOverride(optional): URL to override the default SMART logo. Set tonullto remove the logo.logoBottom(optional): URL to add a logo at the bottom of the widget. Set tonullto remove the bottom logo.
Example:
render(shlinkData, container, {
showDetails: false,
viewerPrefix: 'https://example.com/viewer',
showButtons: ['copy', 'download'],
qrStartsOpen: true,
logoOverride: 'https://example.com/custom-logo.png',
logoBottom: 'https://example.com/bottom-logo.png',
});You can use our supplied CSS to style the widget based on .class, or you can customize the styling. Either way, include a shlinker.css in your page. See src/shlinker.css.
If you render the widget into an explicitly sized div, it will adjust to fit.
Contributions to the SMART Health Links Processing Library are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the library's GitHub repository.
This library is released under the MIT License.