# 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.

> **NOTE:**
For optimal results, it is recommended to implement the Labels Grid Element in a full-width UI configuration rather than within a contained layout. If this does not meet your use case, consider instantiating the [Shipment Summary Element](/apis/shipengine/docs/elements/label-workflow/shipment-summary) to view all labels and details of a single shipment in a responsive UI.


## React Component


```jsx
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,
  onLabelsCSVExportClick,
}) => {
  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,
    showExportCSVButton: 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)}
        onLabelsCSVExportClick = {handleLabelsCSVExportClick()}
        features={labelsGridFeatures}
      />
    </ElementsProvider>
  );
};
```

## SDK


```js
// 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,
      showExportCSVButton: 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),
  onLabelsCSVExportClick: () => handleLabelsCSVExportClick(),
});
```

| 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. |
| `onClickTrackingNumber` | optional | ***function***, `(labelId: string, trackingNumber: string, trackingUrl: string ) => void` An optional callback function with three required parameters: `labelId` which is the ID of the label, `trackingNumber` which is the tracking number of the shipment, and `trackingUrl` which is the URL to track the shipment. The `onClickTrackingNumber` callback will be invoked when the tracking number link is clicked. If not provided, the tracking number will open the tracking URL in a new tab. |
| `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](/apis/shipengine/docs/elements/label-workflow/void-label). |
| `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. |
| `onLabelsCSVExportClick` | optional | ***function***, `() => void` An optional callback function that has no parameters, to be invoked with the onClick event of the 'Export CSV' button. |
| `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. |
| `showExportCSVButton` | ***boolean***, default `false`. This determines whether to show the button to export grid information in CSV format. If set to `true`, the button will be visible. Export has a limit of 10,000 items. This feature is not compatible with the filter trackingStatus, so even if showExportCSVButton is set to `true` will not be visible if trackingStatus is also configured. |



```js
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,
  showExportCSVButton: 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` | False | Displays the current tracking status for the label. |
| `labelStatus` | `allowFilter: boolean` `nickname: string` | False | Displays the current label 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. |