Labels Grid Element

The Labels Grid Element simplifies label management with its intuitive grid interface, allowing users to easily view, print, and void active labels across all shipments, or filter by one specific shipment. By configuring the labelStatus prop, you can control if all labels are shown or if only a specific status of labels are shown.

React Component

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
67
68
69
import { LabelsGrid, ElementsProvider } from '@shipengine/elements';
import { themeConfig } from '../themeConfig';

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

const Foo = ({
  labelStatus,
  onClickPrintForms,
  onClickPrintLabel,
  onClickViewDetails,
  onClickVoidLabel,
  onRowClick,
  onClickExternalShipmentId,
}) => {
  const getToken = useCallback(() => {
    return fetch(tokenPath).then((res) => res.text());
  }, []);

  // configurable features can be set here on the Element
  // or nested in the globalFeatures prop in the ElementsProvider,

const labelsGridFeatures = {
          columns: [
            {
              name: "labelId",
              allowFilter: true,
            },
            {
              name: "shipmentId",
              allowFilter: true,
              nickname: "ShipEngine Shipment ID"
            },
            {
              name: "externalShipmentId",
              nickname: "Marketplace Shipment ID"
            },
            {
              name: "externalShipmentId",
              nickname: "Marketplace Order ID"
            },
            { name: "packages", }
            { name: "recipient" },
            { name: "shippingService" },
            { name: "createdDate" },
            { name: "shipDate" },
            { name: "trackingStatus" },
          ],
          showActions: true
        }

  return (
    <ElementsProvider
      getToken={getToken}
      themeConfig={themeConfig}
      onError={handleError}
    >
      <LabelsGrid.Element
        labelStatus={'completed'}
        onClickPrintForms={printForms()}
        onClickPrintLabel={printLabel()}
        onClickViewDetails={(label) => viewLabelDetails(label)}
        onClickVoidLabel={(label) => voidLabel(label)}
        onRowClick={(label) => handleRowClick(label)}
        onClickExternalShipmentId={(externalShipmentId) => handleExternalShipmentIdClick(externalShipmentId)}
        features={labelsGridFeatures}
      />
    </ElementsProvider>
  );
};

SDK

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
// Creates a new instance of the Elements SDK.
const elements = new ElementsSDK(getToken, {
  onError: (err: Error) => console.error(err),
  themeConfig: themeConfig,
  locale: 'en-US',
  features: {
    labelsGridFeatures: {
          columns: [
            {
              name: "labelId",
              allowFilter: true,
            },
            {
              name: "shipmentId",
              allowFilter: true,
              nickname: "ShipEngine Shipment ID"
            },
            {
              name: "externalShipmentId",
              nickname: "Marketplace Shipment ID"
            },
            {
              name: "externalShipmentId",
              nickname: "Marketplace Order ID"
            },
            { name: "packages", }
            { name: "recipient" },
            { name: "shippingService" },
            { name: "createdDate" },
            { name: "shipDate" },
            { name: "trackingStatus" },
          ],
          showActions: true
        }
  }
});

const labelsGrid = elements.create('labelsGrid', {
  labelStatus: 'completed',
  onClickPrintForms: () => printForms(),
  onClickPrintLabel: () => printLabel(),
  onClickViewDetails: (label) => viewLabelDetails(label),
  onClickVoidLabel: (label) => voidLabel(label),
  onRowClick: (label) => handleRowClick(label),
  onClickExternalShipmentId: (externalShipmentId) => handleExternalShipmentIdClick(externalShipmentId)
});

Args/Props	Required?	Description
`labelStatus`	optional	*string*, Enum: `"processing"` `"completed"` `"error"` `"voided"` The status of the labels you wish to view in the grid. If no value is defined, all labels will be displayed.
`onClickExternalShipmentId`	optional	*function*, `(externalShipmentId: string) => void` is an optional callback function that will be invoked when the user clicks the ID number within the `External Shipment Id` column, if present.
`onClickExternalOrderId`	optional	*function*, `(externalOrderId: string) => void` is an optional callback function that will be invoked when the user clicks the ID number within the `External Order Id` column, if present.
`onClickPrintForms`	optional	*function*, `() => void` An optional callback function that has no parameters, to be invoked with the onClick event of the 'Print Forms' button.
`onClickPrintLabel`	optional	*function*, `() => void` An optional callback function that has no parameters, to be invoked with the onClick event of the 'Print Label' button.
`onClickShipmentNumber`	optional	*function*, `(shipmentNumber: string) => void` is an optional callback function that will be invoked when the user clicks the value within the `Shipment Number` column, if present.
`onClickViewDetails`	optional	*function*, `(label: SE.Label) => void` An optional callback function with one required paramater, `label`, which is the label you wish to view. The onClickViewDetails callback will be invoked with the onClick event of the 'View Details' action button.
`onClickVoidLabel`	optional	*function, `(label: SE.Label) => void` An optional callback function with one required parameter: `label` which is the label that is intended to be voided. The onClickVoidLabel callback will be invoked with the onClick event of the 'Void Label' button. We recommend using this callback to render the* Void Label Element.
`onRowClick`	optional	*function*, `(label: SE.Label) => void` An optional callback function with one required parameter: `label` which is the label populated in the grid row. The `onRowClick` is invoked with the onClick event of the focused grid row.
`features`	optional	*object, see below*. Allows additional configuration of the columns in the grid.

Additional configuration

The features property allows you to show, hide, and/or reorder columns in the grid. This is an optional property, and if not provided, the grid will provide a default view that provides most commonly-used information. All properties on the features object are optional, and will override the default if provided.

Props	Description
`columns`	*array, `{ name: string, ... }[]`. This property takes an array of column definition objects. If provided, this will overwrite* the columns that appear in the grid by default. Only the provided columns will be displayed, and will be displayed in the order given. See below for more information on available columns.
`showActions`	*boolean*, default `true`. This determines whether to show the actions menu on rows when applicable. If set to false, the menu will always be hidden.

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
const labelsGridFeatures = {
          columns: [
            {
              name: "labelId",
              allowFilter: true,
            },
            {
              name: "shipmentId",
              allowFilter: true,
              nickname: "ShipEngine Shipment ID"
            },
            {
              name: "externalShipmentId",
              nickname: "Marketplace Shipment ID"
            },
            {
              name: "externalShipmentId",
              nickname: "Marketplace Order ID"
            },
            { name: "packages", }
            { name: "recipient" },
            { name: "shippingService" },
            { name: "createdDate" },
            { name: "shipDate" },
            { name: "trackingStatus" },
          ],
          showActions: true
        }

The columns array allows you to select the availability and order of columns in the grid from the available columns, by specifing the column name within the name property.

Each column object may have additional nested properties for further configuration.

Additional Property Name	Description
`allowFilter: boolean`	Displays a filter menu at the top of the grid to allow the user to filter rows where the appropriate column ID matches a given string. If the column is present but `allowFilter` is not provided, it will default to `true`.
`nickname: string`	Configurable string to override the default column header.

Column Name	Additional Properties	Visible by Default	Description
`labelId`	`allowFilter: boolean` `nickname: string`	True	Shows the ShipEngine LabelID for the label.
`recipient`	`nickname: string`	True	Displays the recipient's name and address.
`shippingService`	`nickname: string`	True	Displays the carrier and shipping service for the label.
`createdDate`	`nickname: string`	True	Displays the date on which the label was created.
`trackingStatus`	`nickname: string`	True	Displays the current tracking status for the label.
`packages`	`nickname: string`	False	Displays the number of packages or parcels included in the label.
`shipDate`	`nickname: string`	False	Displays the ship date given at time of purchase. Note this is not necessarily the date on which the packages were actually shipped, but the selected ship date for which it was originally purchased.
`shipmentId`	`allowFilter: boolean` `nickname: string`	False	Displays the ShipEngine ShipmentID of the shipment for which the label was created.
`shipmentNumber`	`nickname: string`	False	Displays the Shipment Number assigned to the shipment for which the label was created.
`externalShipmentId`	`nickname: string`	False	Displays the external shipment ID assigned to the shipment at time of shipment creation.
`externalOrderId`	`nickname: string`	False	Displays the external order ID assigned to the shipment at time of shipment creation.