Embed UI components

​

Project setup

​

Prerequisites

The Ampersand UI library requires React v18+.

​

Install the Ampersand React library

In your repo, use npm or yarn to install the package:

npm install @amp-labs/react

or

yarn add @amp-labs/react

​

For versions 1.x.x (legacy)

Version 1.x.x requires chakra-ui peer dependencies.

If you are using yarn, you’ll have to explicitly install the peer dependencies.

yarn add @amp-labs/react @chakra-ui/react @emotion/react @emotion/styled framer-motion

​

Credentials

This library requires your components to be wrapped in the <AmpersandProvider/> context. <AmpersandProvider /> takes these props:

• apiKey: an API key to access Ampersand services. If you don’t have one yet, create one on the API keys page of Ampersand Dashboard.
• project: your Ampersand project name or ID. You can find it on your project’s General Settings page.

​

Example

Here’s an example:

import { AmpersandProvider, InstallIntegration } from '@amp-labs/react';

// For v2.x.x, you must import the Ampersand style sheet once in your application.
import '@amp-labs/react/styles';
import './App.css'; // optional: your own CSS override.

const options = {
  project: 'PROJECT', // Your Ampersand project name or ID.
  apiKey: 'API_KEY',// Your Ampersand API key.
};

function App() {
  return (
    // Wrap all your components inside AmpersandProvider.
    // You can either do this at the App level,
    // or further down in the component tree.
    <AmpersandProvider options={options}>
        // You can use any of the Ampersand components here.
        <InstallIntegration ... />
    </AmpersandProvider>
  )
}

​

Components

​

Install integration

The InstallIntegration component asks your customer for their SaaS credentials, and then guides them through the installation flow for an integration. If they’ve already installed this integration, then the component will display the current configuration of the integration and allow them to update it.

Please note that each group is able to install the integration once, so if someone else with the same groupRef has already installed the integration, then the user will not be able to install the same integration again.

The parameters of the component are:

• integration (string): the name of an integration that you’ve defined in amp.yaml. See Defining integrations.
• consumerRef (string): the ID that your app uses to identify this end user.
• consumerName (string, optional): the display name for this end user.
• groupRef (string): the ID that your app uses to identify a company, team, or workspace. See group.
• groupName (string, optional): the display name for this group.
• onInstallSuccess (function, optional): a callback function that gets invoked after a consumer successfully installs the integration.
• onUpdateSuccess (function, optional): a callback function that gets invoked after a consumer successfully updates an existing integration with the new configuration.
• onUninstallSuccess (function, optional): a callback function that gets invoked after a consumer successfully uninstalls the integration.

Both onInstallSuccess and onUpdateSuccess should be functions with the following signature: (installationId: string, config: Config) => void. Config is an exported type from @amp-labs/react.

 <InstallIntegration 
  integration = {myIntegrationName}
  consumerRef = {userId}
  consumerName = {userFullName}
  groupRef = {teamId}
  groupName = {teamName}
  onInstallSuccess = {(installationId, configObject) =>
    console.log(`Successfully installed ${installationId}`
      + `with configuration ${JSON.stringify(configObject, null, 2)}`)
  }
  onUpdateSuccess = {(installationId, configObject) =>
    console.log(`Successfully updated ${installationId}`
      + ` with configuration ${JSON.stringify(configObject, null, 2)}`)
  }
  onUninstallSuccess = {(installationId) =>
    console.log(`Successfully uninstalled ${installationId}`)
  }
/>

​

Connect provider

The ConnectProvider component allows your customer to put in their SaaS credential, but does not lead them through the installation flow. After their SaaS credential is persisted by Ampersand, you can then make an API request to the CreateInstallation endpoint.

The parameters of the component are:

• provider (string): the name SaaS provider, such as “salesforce”.
• consumerRef (string): the ID that your app uses to identify this end user.
• consumerName (string, optional): the display name for this end user.
• groupRef (string): the ID that your app uses to identify a company, team, or workspace. See group.
• groupName (string, optional): the display name for this group.
• redirectUrl (string, optional): if provided, the page will be redirected to this URL once a consumer successfully connects. This can either be an absolute or relative URL.
• onConnectSuccess (function, optional): a callback function that gets invoked after a consumer successfully connects.
• onDisconnectSuccess (function, optional): a callback function that gets invoked after a consumer successfully disconnects.

Both onConnectSuccess and onDisconnectSuccess should be functions with the following signature: (connection: Connection) => void. Connection is an exported type from @amp-labs/react.

 <ConnectProvider 
  provider = "salesforce"
  consumerRef = {userId}
  consumerName = {userFullName}
  groupRef = {teamId}
  groupName = {teamName}
  redirectUrl = "/connection-success"
  onConnectSuccess = {connection =>
    console.log(`Successfully created connection ${connection.id}`)
  }
  onDisonnectSuccess = {connection =>
    console.log(`Successfully deleted connection ${connection.id}`)
  }
/>

​

Hooks

​

Check if integration is installed

We provide a hook useIsIntegrationInstalled to check if an integration has been installed yet for this group. It takes in 2 parameters:

• integration (string): the name of an integration that you’ve defined in amp.yaml. See Defining integrations.
• groupRef (string): the ID that your app uses to identify a company, team, or workspace. See group.

It returns an object with fields isLoadedchecking if API call is resolved and isIntegrationInstalled indicating whether the integration has already been installed by somebody in the group.

const {
  isLoaded,
  isIntegrationInstalled
} = useIsIntegrationInstalled("read-salesforce", groupRef);

​

Customize styles

To customize the look and feel of Ampersand components, import your own CSS file directly after @amp-labs/react/styles.

You can override CSS variables that are exposed in the variables.css file. By convention, CSS variables that are used in the Ampersand components are named with --amp as a prefix.

import { AmpersandProvider } from '@amp-labs/react';
// Customized style is only supported in v2.x.x
// You only have to import the Ampersand style sheet once in your application.
import '@amp-labs/react/styles';
import './App.css'; // optional: your own css override 

​

Example App.css

:root {
    /* These affect the look and feel of buttons */
    --amp-colors-primary: #4360e0;
    --amp-default-border-radius: 8px;

    /* Override with your own color pallette */ 
    --amp-colors-neutral-25: #FEFEFE;
    --amp-colors-neutral-50: #FDFCFD;
    --amp-colors-neutral-100: #FAFAFC;
    --amp-colors-neutral-200: #F6F5F9;
    --amp-colors-neutral-300: #F1EFF5;
    --amp-colors-neutral-400: #EDEAF2;
    --amp-colors-neutral-500: #E8E5EF;
    --amp-colors-neutral-600: #918E95;
    --amp-colors-neutral-700: #646266;
    --amp-colors-neutral-800: #363638;
    --amp-colors-neutral-900: #1D1D1D;
}

​

Dark mode

Ampersand’s UI components support dark mode. Ensure that you have the following lines in your application’s CSS:

:root {
  color-scheme: light dark;
}

When a user sets their system settings to dark mode, then Ampersand’s UI components will automatically render in dark mode. We do this by making use of the light-dark CSS function in our default colors. You can customize the colors by adding an override CSS file. See Customize styles.

​

Migrating to v2

@amp-labs/react v2.x.x no longer requires Chakra as a dependency, and also provides users with the ability to customize styles. When upgrading from v1.x.x. to v2.x.x, you must add an additional line after importing the library:

import { AmpersandProvider, InstallIntegration } from '@amp-labs/react';

// For v2.x.x, you must import the Ampersand style sheet once in your application.
import '@amp-labs/react/styles';
import './App.css'; // optional: your own CSS override 

​

Troubleshooting

​

Why does does styling look so bare?

You likely forgot to import the stylesheet, please add this line once in your application.

import '@amp-labs/react/styles';