# NewInvitation Embed

Use the NewInvitation embed to invite candidates to the Checkr-Hosted Apply Flow.

## Customize it live

This is the real `NewInvitation` component running in `fakeMode` (canned data, no API calls, no credentials). Restyle and reconfigure it with the controls — every knob maps to a documented [`styles`](#style-the-embed) selector or embed option — then copy the exact code your changes produce.

The following data is captured from the user of this Embed:

* Checkr allows businesses to model their organization as a tree of nodes. A [node](https://docs.checkr.com/#tag/Nodes) selector is shown if the account is configured with more than one node.
* The employment work location. Work location defines where your candidate will be employed.
* The package to be used for the background check. Packages are a list of screenings to be run for a report.
* The email address used to invite the candidate to the background check.
* Optionally, for US-based candidates, a phone number to which the invitation will also be sent.


## Add the embed to your page

The NewInvitation embed may be added to your page either inline or as a modal. Adding the embed inline will render the embed on your application's page. Adding it as a modal allows you to launch the embed from a button or other feature on your page.

### Add the embed inline

Both JavaScript and React may be used to insert the Embed inline in your application. The results shown below are examples of the Embed's default appearance.

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation()
embed.render('#your-placeholder-div')
```

React
```jsx
import {Embeds} from '@checkr/web-sdk'
const NewInvitation = Embeds.NewInvitation.useReact(React, ReactDOM)

return <NewInvitation />
```

Result
### Add the embed as a modal

Use JavaScript to launch the Embed as a modal, for example on the click of a button in your application.

JavaScript
```javascript
const btn = document.getElementById('your-button')

btn.addEventListener('click', event => {
  const embed = new Checkr.Embeds.NewInvitation()
  embed.modal()
})
```

Result
The default modal width is `600px` on desktops and `100%` on mobile devices. Use `width` option to change the desktop width.

```
embed.modal({ width: '700px' })
```

## Add authentication

Add SessionToken based on the [authentication](/embeds/getting-started#add-authentication) section above. For example:

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation({ sessionTokenPath: '/your-backend/session-tokens' })
```

React
```jsx
<NewInvitation sessionTokenPath='/your-backend/checkr-session-tokens' />
```

## Add request callbacks

Request callbacks are triggered when sending an invitation to a candidate is successful or fails.

### onInvitationSuccess

`onInvitationSuccess` is triggered when an invitation is successfully sent to a candidate. Use this callback to capture details like the Checkr Invitation or Candidate id in your system.

JavaScript
```javascript
const handleOnInvitationSuccess = (response) => { console.log(response) }
const embed = new Checkr.Embeds.NewInvitation({onInvitationSuccess: handleOnInvitationSuccess})
```

React
```jsx
const handleOnInvitationSuccess = (response) => { console.log(response) }
<NewInvitation onInvitationSuccess={handleOnInvitationSuccess}/>
```

Callback data
```json
{
  "candidate_id": "00f3d4c23b83e2b845ffd991",
  "candidate_url": "https://dashboard.checkr.com/candidates/00f3d4c23b83e2b845ffd991",
  "created_at": "2021-09-28T03:41:30.722Z",
  "custom_external_status": {
    "code": "invitation_created",
    "message": "Invitation Sent"
  },
  "external_background_check_id": null,
  "external_candidate_id": "external_id",
  "external_job_application_id": null,
  "external_requester_id": null,
  "external_system": "web-sdk",
  "id": "bd6b0537212189fd6a4fa2db",
  "invitation": {
    "created_at": "2021-09-28T03:41:30.722Z",
    "deleted_at": null,
    "expires_at": "2021-12-28T03:41:30.722Z",
    "id": "73a5d217bd981e885841b589"
  },
  "metadata": {},
  "object": {},
  "package": {
    "id": "a44ax285528e6fde7d542192",
    "name": "basic",
    "slug": "basic"
  },
  "report": {
    "created_at": "2021-09-28T03:41:30.722Z",
    "completed_at": null,
    "estimated_completion_time": 1,
    "id": "e44aa283528e6fde7d542194"
  },
  "report_url": "https://dashboard.checkr.com/reports/e44aa283528e6fde7d542194",
  "uri": "background_checks/bd6b0537212189fd6a4fa2db"
}
```

### onInvitationError

`onInvitationError` is triggered when sending an invitation fails. By default, these errors are displayed at the top of the rendered embed within your application. The NewInvitation embed will return all errors generated by the Checkr API.

JavaScript
```javascript
const handleOnInvitationError = (response) => { console.log(response) }
const embed = new Checkr.Embeds.NewInvitation({onInvitationError: handleOnInvitationError})
```

React
```jsx
const handleOnInvitationError = (response) => { console.log(response) }
<NewInvitation onInvitationError={handleOnInvitationError}/>
```

Callback data
```json
{
  "errors": {
    "invitation": [
        "Package not found"
    ]
  }
}
```

## Customize the embed

The NewInvitation embed provides the following options to customize its default behavior.

### Define a custom Candidate ID

You may define a custom candidate ID using the NewInvitation embed to reference Checkr candidates and their background checks. This will create a Checkr candidate with its `custom_id` set to the specified external candidate ID.

You may use this custom ID to map Checkr candidate IDs to objects in your product. You may also use this custom candidate ID as an argument to the [ReportsOverview embed](/embeds/reports-overview-embed), to show all reports for the candidate.

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation({ externalCandidateId : 'your-candidate-id' })
```

React
```jsx
<NewInvitation externalCandidateId='your-candidate-id' />
```

### Add a default candidate email address or phone number

Checkr allows you to set a default value for the NewInvitations embed's email address or phone number. This value will appear in the Embed when launched, and may be modified by your users.

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation({ defaultEmail: "john@doe.com", defaultPhone: "555-867-5309" })
```

React
```jsx
<NewInvitation defaultEmail="john@doe.com" defaultPhone="555-867-5309"/>
```

Result
### Hide the Back Button

In certain use cases, the Back button may be unnecessary. You can hide it from the embed by using the following method:

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation({ hideBackButton: true })
```

React
```jsx
<NewInvitation hideBackButton={true}/>
```

Result
### Add preset values

Use `preset` to specify a fixed value for an available input value. Preset inputs (except email and phone) are not displayed on the embed.

Checkr provides 4 preset values for the NewInvitation Embed:

* presetEmail
* presetPhone
* presetNodeCustomId
* presetPackageSlug
* presetWorkLocation


`presetWorkLocation` can be used to preset two different scenarios

**The full work location**

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation({
  presetEmail: 'john@doe.com',
  presetPhone: '555-867-5309',
  presetNodeCustomId: '1000002',
  presetPackageSlug: 'criminal_drug',
  presetWorkLocation: {country: 'US', state: 'CA', city: 'Los Angeles'}
})
```

React
```jsx
<NewInvitation
  presetEmail='john@doe.com'
  presetPhone='555-867-5309'
  presetNodeCustomId='1000002'
  presetPackageSlug='criminal_drug'
  presetWorkLocation={country: 'US', state: 'CA', city: 'Los Angeles'} />
```

Result
**Only the country**

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation({
  presetEmail: 'john@doe.com',
  presetPhone: '555-867-5309',
  presetNodeCustomId: '1000002',
  presetPackageSlug: 'criminal_drug',
  presetWorkLocation: {country: 'US'}
})
```

React
```jsx
<NewInvitation
  presetEmail='john@doe.com'
  presetPhone='555-867-5309'
  presetNodeCustomId='1000002'
  presetPackageSlug='criminal_drug'
  presetWorkLocation={country: 'US'} />
```

Result
### Define labels and placeholders

Checkr allows you to customize the embed's label and placeholder text for customer input fields.

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation({
  cityLabel: 'This is a city label',
  cityPlaceholder: 'This is a city placeholder',
  countryLabel: 'This is a country label',
  countryPlaceholder: 'This is a country placeholder',
  emailLabel: 'This is an email label',
  emailPlaceholder: 'This is an email placeholder',
  nodeLabel: 'This is a node label',
  nodePlaceholder: 'This is a node placeholder',
  packageLabel: 'This is a package label',
  packagePlaceholder: 'This is a package placeholder',
  phoneLabel: 'This is a phone label',
  phonePlaceholder: 'This is a phone placeholder'
  stateLabel: 'This is a state label',
  statePlaceholder: 'This is a state placeholder'
})
```

React
```jsx
<NewInvitation
  cityLabel='This is a city label'
  cityPlaceholder='This is a city placeholder'
  countryLabel= 'This is a country label'
  countryPlaceholder= 'This is a country placeholder'
  emailLabel='This is an email label'
  emailPlaceholder='This is an email placeholder'
  nodeLabel='This is a node label'
  nodePlaceholder='This is a node placeholder'
  packageLabel='This is a package label'
  packagePlaceholder='This is a package placeholder'
  phoneLabel='This is a phone label'
  phonePlaceholder='This is a phone placeholder'
  stateLabel='This is a state label'
  statePlaceholder='This is a state placeholder'/>
```

Result
### Define filters

You may define filters to limit the packages and nodes displayed to your customers within the Embed.

Filters may be defined based on the parameters included with the [package](https://docs.checkr.com/#tag/Packages) and [node](https://docs.checkr.com/#tag/Nodes) resources within the Checkr API.

This example filters on the node's name, the package's slug, and also the work location country. The embed will display only nodes with names including **central**, only packages including **basic** or **premium** in their slug, and only **Canada** or the **US** as selectable countries.

JavaScript
```javascript
const embed = new Checkr.Embeds.NewInvitation({
  nodeFilter: allNodes =>
    allNodes.filter(node => node.name.toLowerCase().includes('central')),
  packageFilter: allPackages =>
    allPackages.filter(pkg => ['basic', 'premium'].includes(pkg.slug.toLowerCase())),
  workLocationCountryFilter: allCountries =>
    allCountries.filter(country => ['US', 'CA'].includes(country.code))
})
```

React
```jsx
const nodeFilter = allNodes => allNodes.filter(node => node.name.toLowerCase().includes('central'))
const packageFilter =  allPackages => allPackages.filter(pkg => ['basic', 'premium'].includes(pkg.slug.toLowerCase()))
const workLocationCountryFilter = allCountries => allCountries.filter(country => ['US', 'CA'].includes(country.code)

<NewInvitation nodeFilter={nodeFilter} packageFilter={packageFilter} workLocationCountryFilter={workLocationCountryFilter}/>
```

Result
The embed displays filtered packages and nodes.

## Style the embed

Use standard CSS to customize the look and feel of your embeds.

### Adjust the width on the page

By default, Embeds are rendered using the full width of their container `div`. Adjust the width of the container `div` on your page to control the width of the embed.

### Customize the theme

Embeds include a default theme, and allow users to both customize this default theme or build a custom theme from scratch.

* To customize the default theme, specify the styles you wish to override.
* To build a theme from scratch, use the `useBaseline` option.


**Note:** An embed's styles neither inherit nor conflict with your site's styles. Embed UIs are complex, have a specific structure, and therefore have specific styling needs. Inheriting an external page's styling will break the embed.

The following classes may be targeted by CSS.

| Embed CSS selectors |  | Loading CSS selectors |  |
|  --- | --- | --- | --- |
| .btn | .header | .checkr-embeds-loading-container | .loading-bar |
| .btn-loading | .new-invitation | .rect1 | .rect2 |
| .btn-primary | .select-city | .rect3 | .rect4 |
| .btn-submit | .select-country | .rect5 |  |
| .btn-success | .select-node |  |  |
| .form-control | .select-package |  |  |
| .form-control-typeahead | .select-state |  |  |
| .form-control-clear-typeahead | .success-view |  |  |
| .form-group | .typeahead-option-selected |  |  |
| .form-group-email | .typeahead-option |  |  |
| .form-group-typeahead | .typeahead-options |  |  |
| .form-label | .work-location |  |  |
| .form-label-typeahead |  |  |  |


### Edit the default theme

To edit the default theme, specify new values for any of the default CSS selectors listed above.

JavaScript
```javascript
const styles = {
  '.btn-primary': {
    background: '#0a8080',
  },
  '.header': {
    'font-size': '150%',
    'font-weight': 'bold',
    color: '#F45D48',
  },
  '.form-label': {
    'font-weight': '700',
  },
  '.form-control': {
    background: '#F3FAFB',
    padding: '0.5rem',
  },
  '.form-control:focus, .form-control:focus-visible': {
    'border-color': '#0a8080',
  },
};

const embed = new Checkr.Embeds.NewInvitation({ styles })
```

Result
The embed renders with the customized theme.

### Define a custom theme

To define a custom theme from scratch, set `useBaseline` to `true`, then specify values for any of the selectors listed below. If values are not set for a selector, the embed will render without styles for that value.

JavaScript
```jsx
const styles = {
  useBaseline: true,
  '.btn': {
    'border-radius': '0.375rem',
    color: '#ffffff',
  },
  '.btn-primary': {
    'background-color': '#fcd669',
  },
  '.btn-submit': {
    display: 'block',
    width: '100%',
  },
  '.btn-submit:disabled': {
    opacity: 0.7,
  },
  '.form-control': {
    'background-color': '#7795f8',
    border: '0',
    color: '#fff',
    padding: '0.5rem',
    width: 'calc(100% - 1rem)',
  },
  '.form-control::placeholder': {
    color: '#87bbfd',
  },
  '.form-control-container': {
    display: 'inline-block',
    position: 'relative',
    width: '70%',
  },
  '.form-label': {
    color: '#c4f0ff',
    display: 'inline-block',
    padding: '0.5rem 1rem',
    'text-overflow': 'ellipsis',
    'white-space': 'nowrap',
    width: '30%',
  },
  '.form-group': {
    'background-color': '#7795f8',
    'border-radius': '0.375rem',
    'box-shadow':
      '0 6px 9px rgb(50 50 93 / 6%), 0 2px 5px rgb(0 0 0 / 8%), inset 0 1px 0 #829fff',
    'margin-bottom': '1.5rem',
  },
  '.header': {
    display: 'none',
  },
  '.new-invitation': {
    'background-color': '#6772e5',
    'border-radius': '0.375rem',
    padding: '1.8rem 2rem',
  },
  '.success-view': {
    color: '#fff',
  },
  '.typeahead-option-selected': {
    'background-color': '#87bbfd',
    color: '#fff',
  },
  '.typeahead-options': {
    'background-color': '#fff',
    'border-radius': '0.375rem',
  },
};

<NewInvitation styles={styles} />
```

Result
The embed renders with the custom baseline theme.