React JavaScript SDK to interact with Sigma Computing's Embed API
npm install @sigmacomputing/react-embed-sdkTo use the react-embed-sdk in your project, you can install it using your node package manager.
Using npm:
``code`
npm install @sigmacomputing/react-embed-sdk
yarn:
`code`
yarn add @sigmacomputing/react-embed-sdk
pnpm:
`code`
pnpm add @sigmacomputing/react-embed-sdk
The library provides hooks that combine the lower level listeners and mutations to provide a more ergonomic API.
#### useSigmaIframe
A hook that returns a ref to be used with a Sigma iframe element, and the loading and error state of the embed.
`typescript`
useSigmaIframe(): {
iframeRef: React.RefObject
loading: boolean;
error: WorkbookErrorEvent | null;
variables: Record
}
Example usage:
` Loading... Error: {error.message}tsx`
function MyEmbed() {
const { iframeRef, loading, error } = useSigmaIframe();
return (
<>
{loading &&
{error &&
className={loading || error ? "hidden" : "show"}
ref={iframeRef}
{/ The embed url to load /}
src="https://app.sigmacomputing.com/embed"
/>
>
);
}
#### useWorkbookVariables
A hook that returns functions to get and set the variables in a workbook.
`typescript`
useWorkbookVariables(iframeRef: React.RefObject
getVariables: () => Promise
setVariables: (variables: Record
}
Example usage:
`tsx`
function MyEmbed() {
const { getVariables, setVariables } = useWorkbookVariables(iframeRef);
return (
<>
onClick={async () => {
const variable = await getVariables();
}}
name="get-variables"
>
Get Filters
>
);
}
#### usePageHeight
A hook that returns the height of the page in the iframe. This HAS to be used with the responsive_height URL Parameter.
`typescript`
usePageHeight(iframeRef: React.RefObject
Example usage:
`tsx`
function MyEmbed() {
const { iframeRef } = useSigmaIframe();
const height = usePageHeight(iframeRef);
return (
<>
style={{ height }}
ref={iframeRef}
src="https://app.sigmacomputing.com/embed?:responsive_height=true"
/>
>
);
}
These are functions that can be used to listen for events from the embed, and react to them.
#### useWorkbookLoaded
Listen for a workbook loaded event, and execute the given callback when it occurs.
`typescript`
useWorkbookLoaded(iframeRef: React.RefObject
#### useWorkbookError
Listen for a workbook error event, and execute the given callback when it occurs.
`typescript`
useWorkbookError(iframeRef: React.RefObject
#### useWorkbookDataLoaded
Listen for a workbook data loaded event, and execute the given callback when it occurs.
`typescript`
useWorkbookDataLoaded(iframeRef: React.RefObject
#### useVariableChange
Listen for a workbook variable change event, and execute the given callback when it occurs.
`typescript`
useVariableChange(iframeRef: React.RefObject
#### useTableCellSelect
Listen for a table cell select event, and execute the given callback when it occurs.
`typescript`
useTableCellSelect(iframeRef: React.RefObject
#### useWorkbookPublished
Listen for a workbook published event, and execute the given callback when it occurs.
`typescript`
useWorkbookPublished(iframeRef: React.RefObject
#### useWorkbookFullScreen
Listen for a workbook full screen event, and execute the given callback when it occurs.
`typescript`
useWorkbookFullScreen(iframeRef: React.RefObject
#### useWorkbookPageHeight
Listen for a workbook page height event, and execute the given callback when it occurs. Needs to be used with the responsive_height URL Parameter.
`typescript`
useWorkbookPageHeight(iframeRef: React.RefObject
#### useWorkbookSelectedNode
Listen for a workbook selected node event, and execute the given callback when it occurs.
`typescript`
useWorkbookSelectedNode(iframeRef: React.RefObject
#### useWorkbookPivotTableCellSelect
Listen for a pivot table cell select event, and execute the given callback when it occurs.
`typescript`
useWorkbookPivotTableCellSelect(iframeRef: React.RefObject
#### useWorkbookChartValueSelect
Listen for a chart value select event, and execute the given callback when it occurs.
`typescript`
useWorkbookChartValueSelect(iframeRef: React.RefObject
#### useWorkbookCurrentVariables
Listen for a workbook current variables event, and execute the given callback when it occurs. This is to be used when workbookVariablesList is called.
`typescript`
useWorkbookCurrentVariables(iframeRef: React.RefObject
#### useWorkbookBookmarkOnCreate
Listen for a workbook bookmark create event, and execute the given callback when it occurs.
`typescript`
useWorkbookBookmarkOnCreate(iframeRef: React.RefObject
#### useWorkbookBookmarkOnChange
Listen for a workbook bookmark change event, and execute the given callback when it occurs.
`typescript`
useWorkbookBookmarkOnChange(iframeRef: React.RefObject
#### useWorkbookBookmarkOnUpdate
Listen for a workbook bookmark update event, and execute the given callback when it occurs.
`typescript`
useWorkbookBookmarkOnUpdate(iframeRef: React.RefObject
#### useWorkbookBookmarkOnDelete
Listen for a workbook bookmark delete event, and execute the given callback when it occurs.
`typescript`
useWorkbookBookmarkOnDelete(iframeRef: React.RefObject
#### useWorkbookChartError
Listen for a workbook chart error event, and execute the given callback when it occurs.
`typescript`
useWorkbookChartError(iframeRef: React.RefObject
#### useWorkbookExploreKeyOnChange
Listen for a workbook explore key change event, and execute the given callback when it occurs.
`typescript`
useWorkbookExploreKeyOnChange(iframeRef: React.RefObject
#### useUrlOnChange
Listen for a url change event, and execute the given callback when it occurs.
`typescript`
useUrlOnChange(iframeRef: React.RefObject
#### useWorkbookIdOnChange
Listen for a workbook id change event, and execute the given callback when it occurs.
`typescript`
useWorkbookIdOnChange(iframeRef: React.RefObject
These are functions that can be used to send messages to the embed. They may cause an event to be emitted from the embed.
#### getWorkbookVariables
Send a message to the embed to list the current variables. This will cause a workbook:variables:current event to be emitted from the embed, and can be used with the useWorkbookCurrentVariables function.
`typescript`
getWorkbookVariables(iframeRef: React.RefObject
#### updateWorkbookVariables
Send a message to the embed to update the variables.
`typescript`
updateWorkbookVariables(iframeRef: React.RefObject
#### createWorkbookBookmark
Send a message to the embed to create a bookmark.
`typescript`
createWorkbookBookmark(iframeRef: React.RefObject
#### updateWorkbookBookmark
Send a message to the embed to update the current bookmark.
`typescript`
updateWorkbookBookmark(iframeRef: React.RefObject
#### deleteWorkbookBookmark
Send a message to the embed to delete the given bookmark.
`typescript`
deleteWorkbookBookmark(iframeRef: React.RefObject
#### selectWorkbookBookmark
Send a message to the embed to select the given bookmark. If no bookmarkId is provided, the current bookmark will be deselected.
`typescript`
selectWorkbookBookmark(iframeRef: React.RefObject
#### updateWorkbookFullscreen
Send a message to the embed to toggle the fullscreen state of the given element.
`typescript`
updateWorkbookFullscreen(iframeRef: React.RefObject
#### updateWorkbookSelectedNodeId
Send a message to the embed to update the selected element. Can be a pageId or elementId.
`typescript`
updateWorkbookSelectedNodeId(iframeRef: React.RefObject
#### updateWorkbookSharingLink
Send a message to the embed to update the sharing link.
`typescript``
updateWorkbookSharingLink(iframeRef: React.RefObject