Elements React Components

The @shipengine/elements package provides the full suite of ShipEngine Elements as React components.

Quick Start

1
npm install @shipengine/elements

Install Peer Dependencies:

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

Elements Provider

Render an Elements provider at the root of your React app so that it is available everywhere you need it.

Available to all descendants of the ElementsProvider:

A batteries-included client for accessing ShipeEngine API endpoints with a shared cache and lifecycle management via react hooks.
A theme, which can be re-defined at instantiation via the themeConfig prop.
Configurable features, available via the features prop.

Initialize Elements

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
49
50
51
52
53
import { PurchaseLabel, ElementsProvider } from '@shipengine/elements';
import { themeConfig } from '../themeConfig';

const tokenPath = '/path/to/token/endpoint';

const Foo = ({ shipments }) => {
  const [selectedShipment, setSelectedShipment] = useState();

  const getToken = useCallback(() => {
    return fetch(tokenPath).then((res) => res.text());
  }, []);

  return (
    <ElementsProvider
      getToken={getToken}
      themeConfig={themeConfig}
      onError={handleError}
      getToken={getToken}
      features={{
        globalFeatures: {
          enabledShipEngineCarriers: [
            'ups',
            'stamps_com'
          ]
          enabledExternalCarriers: [
            'apc',
            'asendia',
            'better_trucks',
            'courierpost',
            'dpd',
            'seko',
            'ups',
            'yodel',
          ],
        }
      }}
    >
      <ul>
        {shipments.map((shipment) => (
          <li>
            <button onClick={() => setSelectedShipment(shipment)}>
              Order #{shipment.shipmentId}
            </button>
          </li>
        ))}
      </ul>

      {selectedShipment && (
        <PurchaseLabel.Element shipmentId={selectedShipment.shipmentId} />
      )}
    </ElementsProvider>
  );
};

Args/Props	Description
`getToken`	function, required A callback function that fetches and refreshes the tokens used by Elements. Check out the Elements Getting Started guide for more detailed information about generating Elements tokens.
`baseURL`	string, optional A fully qualified domain name used as the base URL to route all API calls from the Elements. This is defaulted to `https://elements.shipengine.com`
`container`	HTMLElement, optional A DOM element that the components will be mounted to. A shadow root will be created on this container. If not provided, the components will be mounted to a `div` with the ID `elements-container`, and a shadow root will be created on that `div`.
`defaultQueryClientOptions`	object, optional Initialization options of the ReactQuery client. See the QueryClient Docs for more info.
`emotionCacheShadowRootContainer`	ShadowRoot, optional *Deprecated* A reference to a shadow root used for isolating the Elements style sheets, CSS resets, and emotion.js cache.
`features`	object, optional A feature flag configuration object for turning features on and off. See Configuring Elements Features for a comprehensive list of features.
`headers`	object, optional Optional HTTP headers to be sent with all requests.
`locale`	string, optional Defaults to `en-us`
`onApiError`	object, optional Callback function that will be executed whenever there is an error within the API.
`onError`	function, optional An optional callback function to be invoked when an error occurs during a request to the API.
`scope`	string, optional Element id to apply the theme, font family, and CSS reset. By default, the font will be applied to the body element, and the reset will be applied to the root HTML element.configured.
`themeConfig`	object, optional The theme configuration object. Check out the theming documentation to learn more about theming your Elements integration.

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.

Params	Description
`enabledExternalCarriers`	string[], optional List external carrier codes for carriers that can be registered through the Connect External Carrier Element. If this is omitted, external carriers cannot be registered. See the carriers section in the getting started guide for more information. IMPORTANT: If you exclude this property, or set the value to an empty array without including any supported carrier codes, users will not be able to view and connect External Carriers in the Account Settings Element. or the Manage External Carriers Element
`enabledShipEngineCarriers`	string[], optional List of ShipEngine carrier codes for carriers that can be registered through the Onboarding Element. See the carriers section in the getting started guide for more information. IMPORTANT: If you exclude this property, or set the value to an empty array without including any supported carrier codes, users will encounter an error that will prevent them from advancing through the onboarding process within the Onboarding Element and will not be able to access the Carrier Services Element.
`poweredByShipEngine`	boolean, optional Enables the `Powered by ShipEngine` logo in the footer various elements.

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.

Params	Description
`purchaseLabelFeatures`	string[], optional See Purchase Label Features for a comprehensive list.
`shipmentSummaryFeatures`	string[], optional See Shipment Summary Features for a comprehensive list.
`accountSettingsFeatures`	string[], optional See Account Settings Features for a comprehensive list.
`labelsGridFeatures`	string[], optional See Labels Grid Features for a comprehensive list.

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 @shipengine/react-api package required by Elements includes hooks that can be used to perform API operations such as creating shipments. Note that these hooks must be used from a component within the context of your <ElementsProvider> 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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
import { useState, useEffect } from 'react';
import {
  useCreateShipment,
  PurchaseLabel,
  Currency,
} from '@shipengine/elements';

export function CreateShipmentExample() {
  const [shipmentId, setShipmentId] = useState('');
  const { mutateAsync: apiCreateShipment } = useCreateShipment();

  useEffect(() => {
    async function createNewShipment() {
      const response = await apiCreateShipment({
        shipTo: {
          name: 'Benjamin Biggs',
          phone: '+44 44 4444 4444',
          addressLine1: "Dean's Yard",
          cityLocality: 'London',
          stateProvince: '',
          postalCode: 'SW1P 3PA',
          countryCode: 'UK',
        },
        shipFrom: {
          name: 'John Doe',
          companyName: 'Example Corp',
          phone: '333-333-3333',
          addressLine1: '4301 Bull Creek Rd',
          cityLocality: 'Austin',
          stateProvince: 'TX',
          postalCode: '78731',
          countryCode: 'US',
        },
        packages: [
          {
            packageCode: 'package',
            weight: { value: 20, unit: 'ounce' },
            dimensions: { height: 6, width: 12, length: 24, unit: 'inch' },
            products: [
              {
                description: 'Pizza',
                quantity: 2,
                value: {
                  currency: Currency.USD,
                  amount: 20,
                },
                sku: '1234ABCD',
                harmonizedTariffCode: '1905.90.9060',
                countryOfOrigin: 'US',
              },
            ],
          },
        ],
      });
      if (!response.hasErrors) {
        setShipmentId(response.shipments[0].shipmentId);
      }
    }

    if (!shipmentId) {
      createNewShipment();
    }
  }, [shipmentId, apiCreateShipment]);

  return <>{shipmentId && <PurchaseLabel.Element shipmentId={shipmentId} />}</>;
}

Only the shipTo and shipFrom 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 ShipEngine API React Hooks provided by Elements, see the Shipengine Elements API Clients documentation.