Elements SDK

The Elements SDK is a JavaScript SDK for implementing ShipEngine Elements. You can install it via NPM or access it through our CDN.

Quick Start

1
npm install @shipengine/elements-sdk

Install Peer Dependencies:

1
npm install [email protected] [email protected] [email protected] [email protected] @emotion/[email protected]

Elements CDN

The ShipEngine Elements SDK can be included in any page by loading the bundle directly from the Elements CDN. If desired, you may specify a particular version of the SDK by using the following filename format: https://cdn.shipengine.com/shipengine-elements-sdk.<major_version>.<minor-version>.<patch-version>.mjs. You may omit any level of version number to always load the latest at that level. For example, shipengine-elements-sdk.1.2.34.mjs will pull version 1.2.34, while shipengine-elements-sdk.1.mjs will pull the latest minor and patch version for major version 1.

1
2
3
4
5
import { ElementsSDK } from 'https://cdn.shipengine.com/shipengine-elements-sdk.mjs';

// or

<script src="https://cdn.shipengine.com/shipengine-elements-sdk.mjs"></script>

Initialize Elements

You'll need to use the Elements SDK class constructor to initialize Elements. This constructor has three arguments:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Creates a new instance of the Elements SDK.
const elements = new ElementsSDK(
  getToken,
  {
    onError: (err: Error) => console.error(err),
    baseURL: 'https://elements.shipengine.com',
    themeConfig: themeConfig,
    locale: 'en-US',
    features: {
      globalFeatures: {
        enabledShipEngineCarriers: ['ups', 'stamps_com'],
        enabledExternalCarriers: [
          'apc',
          'asendia',
          'better_trucks',
          'courierpost',
          'dpd',
          'seko',
          'ups',
          'yodel',
        ],
      },
    },
  },
  'elementsRoot'
);

Initialization Parameters

Configuring Elements Features

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
features={{
        globalFeatures: {
          enabledShipEngineCarriers: [
            'ups',
            'stamps_com'
          ]
          enabledExternalCarriers: [
            'apc',
            'asendia',
            'better_trucks',
            'courierpost',
            'dpd',
            'seko',
            'ups',
            'yodel',
          ],
        },
          purchaseLabelFeatures: { ... },
          shipmentSummaryFeatures: { ... },
          accountSettingsFeatures: { ... },
          labelsGridFeatures: { ... }
      }}

Global Features

The following properties are configured within the globalFeatures property.

Global features are set within the features parameter of the Elements SDK class constructor and cannot be overridden within Element specific feature props.

Element specific Features

We recommend configuring the features you want to use in the Elements Provider or the SDK constructor for the Element. However, if you need to override features for a specific Element, you can use the feature prop for that Element, provided the Element supports it.

Rendering Elements

elements.create(element)

➤

Elements

• accountSettings
• carrierServices
• connectExternalCarrier
• labelLayout
• labelWorkFlow
• manageCarriers
• manageExternalCarriers
• manageFunding
• manageWarehouses
• onboarding
• paymentMethodSettings
• purchaseLabel
• shipmentSummary
• transactionHistory
• unitSettings
• voidLabel
• labelsGrid

elements.destroy()

Removes Elements from the DOM and destroys it. A destroyed Element instance can not be re-activated or re-mounted to the DOM.

elements.getClient()

Returns an instance of the ShipEngine Elements API JavaScript client. This client can be used to interact directly with the ShipEngine API.

If no parameters are passed to getClient(), the client will be configured based off of the initialization parameters passed to the Elements SDK constructor. If desired, you may pass a token and configuration object to the getClient() method to specify a different configuration:

1
2
3
4
5
const token = await getToken();
const apiClient = elements.getClient(token, {
  getToken,
  onApiError: myOtherErrorHandler,
});

Side Panel Methods (deprecated)

While working with the Elements SDK, you probably noticed methods for rendering individual Elements in a side panel. Methods like onboardUser or purchaseLabel, accessible via the Elements SDK class, have been deprecated in Elements v2 and will be removed in future versions.

Element Render Methods

There are two ways to render Elements in your application:

The Elements SDK allows you to place Elements in any container in you app, but the Elements were designed to look best at a view port width of 440 to 800 pixels.

element.mount(domElement, props)

Before you mount an Element, you must create a container DOM element. The mount method attaches your Element to the DOM. mount accepts either an ID Attribute (e.g., purchaseLabelId) or a DOM element as well as the Elements props. See the documentation for that Element for more information on its props.

You may encounter an issue where the container DOM element wrapping a ShipEngine Element does not automatically resize to fit the component's content. This can lead to layout problems, particularly when working in plain HTML, CSS, and JavaScript environments.

To resolve this, we recommend applying specific CSS styles to the wrapper element where the Element is rendered:

1
2
3
4
5
.wrapper-class {
  min-height: 100px; /* Ensures the wrapper has a minimum height to prevent collapsing */
  max-height: 1000px; /* Prevents the wrapper from growing excessively */
  overflow-y: scroll; /* Allows scrolling for content larger than the max-height */
}

If you're using a framework like React, Vue, or Angular, you are unlikely to encounter this issue, as these frameworks typically handle dynamic DOM sizing automatically. However, this CSS solution is particularly useful when working in environments that rely solely on raw HTML, CSS, and JavaScript

1
2
3
4
5
6
7
<div id="purchaseLabelId">
  <!-- Purchase Label Element will be inserted here. -->
</div>

<script>
  purchaseLabel.mount('purchaseLabelId');
</script>

element.update(props)

Updates the props for the element

1
2
// updates the shipment Id of the purchase label element
purchaseLabel.update({ shipmentId: 'se-1198001' });

element.unmount()

Unmounts the Element from the DOM. Call the element.mount() method to re-attach it to the DOM.

1
purchaseLabel.unmount();

element.renderSidePanel(props)

Renders the Element inside a side panel. The method accepts the Elements props as well as the props for the side panel that it is rendered in side of.

➤

Side Panel Props

Args/Props	Description
header	ReactNode, optional Component to use as the header of the component
footer	ReactNode, optional Component to use as the footer of the component
position	string, optional Value indicating in which side of the screen the component should be placed. Either right or left
size	string, optional Value indicating a predefined size. Either regular or large
containerId	string, optional Id of the container from which the SidePanel will get the height and top
onBackdropClick	function, optional An optional async/sync callback to be executed when click is performed on the outside of the side panel
applyBackdropToBody	boolean, optional Flag to indicate if the backdrop should be placed inside the body

➤

Side Panel Header Props

Args/Props	Description
title	string, required Side panel title
closeButtonTooltip	string, optional Text rendered inside the side panel close button tool tip.
closeAriaLabel	string, optional Aria label for the close button
onClickClose	function, optional Optional callback function invoked when the side panel close button is clicked

1
2
3
4
5
purchaseLabel.renderSidePanel({
  elementProps: { shipmentId: 'se-11975001' },
  sidePanelHeaderProps: { title: 'Purchase a Label' },
  sidePanelProps: { position: 'left' },
});

element.closeSidePanel()

Closes the currently opened side panel.

1
purchaseLabel.closeSidePanel();

Creating Shipments

If you wish to purchase a label using pre-populated values in the Purchaselabel forms, the recommended way to define the shipment values is to create a new shipment using the ShipEngine API, and then pass the new Shipment ID to the PurchaseLabel or LabelWorkflow Element.

The Elements SDK provides an API client which can be used to generate the shipment using the same authentication token used by Elements. See the example below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
const client = elements.getClient(await getToken());
const response = await client.shipments.create({
  ship_to: {
    name: 'Benjamin Biggs',
    phone: '+44 44 4444 4444',
    address_line1: "Dean's Yard",
    city_locality: 'London',
    postal_code: 'SW1P 3PA',
    country_code: 'UK',
  },
  ship_from: {
    name: 'John Doe',
    company_name: 'Example Corp',
    phone: '333-333-3333',
    address_line1: '4301 Bull Creek Rd',
    city_locality: 'Austin',
    state_province: 'TX',
    postal_code: '78731',
    country_code: 'US',
  },
  packages: [
    {
      weight: { value: 20, unit: 'ounce' },
      dimensions: { height: 6, width: 12, length: 24, unit: 'inch' },
      products: [
        {
          description: 'Pizza',
          quantity: 2,
          value: {
            currency: 'USD',
            amount: 20,
          },
          sku: '1234ABCD',
          harmonized_tariff_code: '1905.90.9060',
          country_of_origin: 'US',
        },
      ],
    },
  ],
});
const shipmentId = response.data.shipments[0].shipmentId;

const purchaseLabel = elements.create('purchaseLabel');
purchaseLabel.renderSidePanel({
  elementProps: {
    shipmentId: this.shipmentId,
  },
});

Only the ship_to and ship_from properties are required; The rest may be left blank to be filled in by the user in the Element. The packages.products array is used for Customs information, and is not generally required for local shipments.

For more information on the available fields within the Shipment object, see the ShipEngine API documentation. For additional functionality provided by the Elements API Client, see the ShipEngine Elements API Clients documentation.