Embedding a Component

Embedding Components requires two steps. First, generate a Component URL from Check’s API and embed that URL into an app using the Component SDK. Each page reload requires a new Component URL to be generated for security purposes.

The following steps will embed the Component in a div. The div can be placed in a sidebar, a modal, or directly on your app’s page. Highlighted in the Working with Check Components guide are different design patterns you can follow for embedding a Component.

1. Generate a Component URL

Make a POST request to the Component endpoint (full list here) to generate a Component URL. For this example, we’re generating a Company’s Tax Setup Component. This should be a server-side request.

/companies/{company_id}/components/tax_setup

This endpoint will return a URL that you will embed in your app.

2. Embed the Component URL (example in React v16.8+)

a) Create a function called importScript().

const importScript = (resourceUrl) => {
 useEffect(() => {
   const script = document.createElement('script');
   script.src = resourceUrl;
   script.async = true;
   document.body.appendChild(script);
   return () => {
     document.body.removeChild(script);
   };
 }, [resourceUrl]);
};

export default importScript;

b) Import the Component SDK via the importScript() in your app.js or index.js.

importScript('https://cdn.checkhq.com/component-initialize.js');

📘

Alternative way to import Component SDK

Instead of steps a) and b), you can alternatively embed the SDK as a script tag directly in HTML.

<script src=”https://cdn.checkhq.com/component-initialize.js” />

c) Create a function to load the Component. In this example case, we’ll use the Company Tax Setup Component.

const loadComponent = (componentLink, componentDivId) => {
  try {
    const handler = window.CheckComponent.create({
      link: componentLink,
      onEvent: (event, data) => {
        // handle Check Component events
      },
    });
    handler.open();
    const componentElement = document.getElementById(
      'check-component-embedded-div',
    );
    if (componentElement) {
      const componentHolder = document.getElementById(componentDivId);
      componentHolder.appendChild(componentElement);
    }
  } catch (err) {
    // handle error
  }
};

❗️

Remember to close the Component handler

It's important to close the handler once the user finishes using a Component (i.e. when closing a modal containing the Component). Run the following function handler.close() to remove it from the DOM. This will avoid the Component being cached on the page which may result in it being loaded again at the next call to handler.open().

📘

TypeScript Note

If you are using TypeScript, whenever you reference the CheckComponent object from the window object, we recommend adding a //@ts-ignore comment above that line (view the example below). This suppresses the ‘property does not exist’ error that your development environment may report because the CheckComponent object will only be added to the window object at runtime.

// @ts-ignore
const handler = window.CheckComponent.create({
  link: componentLink,
  onEvent: (event, data) => {},
});

d) Render the Component by specifying the ID of the div you want your Component embedded in. In this example, we use: my_component_holder, but you can name it whatever you want.

useEffect(() => {
   loadComponent(componentLink, 'my_component_holder');
 }, []);

 return (
   <div>
     <div id="my_component_holder" />
   </div>
 );

Check Components SDK

The Check Components SDK is hosted here:

https://cdn.checkhq.com/component-initialize.js

The SDK gives you access to the CheckComponent object which can create an API handler object.

CheckComponent.create() Parameters

ParameterUseDefault
linkRequired. The generated Component URL.N/A
onEventOptional. A callback for state changes to the Component.N/A
appearanceOptional Object specifying customization settings for Components. Learn more in our Customizing Components guide.N/A
divIdOptional. Overrides the default check-component-embedded-div div ID, useful for embedding multiple components on the same page.N/A
allowProcessingPeriodEdits:warning: Run Payroll Component only, Optional. Boolean flag for whether to allow users to be able to edit processing period for a payroll in the Run Payroll Component. If not provided, the Component defaults to not allowing processing period edits. If true, will only appear for employers approved for accelerating processing.false
allowPaydayEdits:warning: Run Payroll Component only, Optional. Boolean flag for whether to allow users to be able to edit paydays for a payroll in the Run Payroll Component. If not provided, the Component defaults to allowing payday edits.

Note that editing a payroll's payday will remove it from its current pay schedule.
true

Handler API

MethodUse
handler.open()Adds the Component to the DOM.
handler.close()Removes the Component from the DOM.

Live Example

Want a live example? You can play around with Components in our Codepen Demo.


What’s Next

In the next guide, we'll go over how to handle events from Check Components.