{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/elements/elements-sdk","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/elements/elements-sdk","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/elements/elements-sdk","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Elements SDK","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"elements-sdk","__idx":0},"children":["Elements SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Elements SDK is a JavaScript SDK for implementing ShipEngine Elements. You can install it via NPM or access it through our CDN."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-start","__idx":1},"children":["Quick Start"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install @shipengine/elements-sdk\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"install-peer-dependencies","__idx":2},"children":["Install Peer Dependencies:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install react@17.x react-dom@17.x i18next@22.x react-i18next@11.x @emotion/react@11.x\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"elements-cdn","__idx":3},"children":["Elements CDN"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://cdn.shipengine.com/shipengine-elements-sdk.<major_version>.<minor-version>.<patch-version>.mjs\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You may omit any level of version number to always load the latest at that level. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipengine-elements-sdk.1.2.34.mjs"]}," will pull version 1.2.34, while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipengine-elements-sdk.1.mjs"]}," will pull the latest minor and patch version for major version 1."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"import { ElementsSDK } from 'https://cdn.shipengine.com/shipengine-elements-sdk.mjs';\n\n// or\n\n<script src=\"https://cdn.shipengine.com/shipengine-elements-sdk.mjs\"></script>\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"initialize-elements","__idx":4},"children":["Initialize Elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll need to use the Elements SDK class constructor to initialize Elements. This constructor has three arguments:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Token Callback Function (required):"]}," This function, a key component of the Elements SDK, fetches and refreshes the tokens used by Elements. Check out the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/getting-started"},"children":["Elements Getting Started guide"]}," for more detailed information about generating Elements tokens."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initialization Parameters (optional):"]}," This object allows you to customize various aspects of the Elements SDK. It's optional; See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#initialization-parameters"},"children":["initialization parameters section"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Container (optional):"]}," An HTML ID or HTML element that the Elements React root and CSS reset will be mounted to. The SDK uses a shadow root to isolate its CSS styles from the rest of your application, preventing conflicts and ensuring consistent styling. If you provide a container, the SDK will create a shadow root on that container and render the elements within it. If you don't provide a container, the SDK will create a new container element with a shadow root and append it to the document body."]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"// Creates a new instance of the Elements SDK.\nconst elements = new ElementsSDK(\n  getToken,\n  {\n    onError: (err: Error) => console.error(err),\n    baseURL: 'https://elements.shipengine.com',\n    themeConfig: themeConfig,\n    locale: 'en-US',\n    features: {\n      globalFeatures: {\n        enabledShipEngineCarriers: ['ups', 'stamps_com'],\n        enabledExternalCarriers: [\n          'apc',\n          'asendia',\n          'better_trucks',\n          'courierpost',\n          'dpd',\n          'seko',\n          'ups',\n          'yodel',\n        ],\n      },\n    },\n  },\n  'elementsRoot'\n);\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["WARNING:"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["emotionCacheShadowRootContainer"]}," property is ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["deprecated"]}," but still supported for backward compatibility. We recommend removing it from your code and relying on the SDK's default shadow DOM implementation."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"initialization-parameters","__idx":5},"children":["Initialization Parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Args/Props"},"children":["Args/Props"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseURL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," A fully qualified domain name used as the base URL to route all API calls from the Elements. This is defaulted to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://elements.shipengine.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["defaultQueryClientOptions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Initialization options of the ReactQuery client. See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://tanstack.com/query/latest/docs/reference/QueryClient"},"children":["QueryClient Docs"]}," for more info."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["emotionCacheShadowRootContainer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["ShadowRoot"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Deprecated"]}]}," A reference to a shadow root used for isolating the Elements style sheets, CSS resets, and emotion.js cache."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["features"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," A feature flag configuration object for turning features on and off. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#configuring-elements-features"},"children":["Configuring Elements Features"]}," for a comprehensive list of features."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Optional HTTP headers to be sent with all requests."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locale"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en-us"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onApiError"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Callback function that will be executed whenever there is an error within the API."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["function"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," An optional callback function to be invoked when an error occurs during a request to the API."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["themeConfig"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," The theme configuration object. Check out the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/elements-guide#theming"},"children":["theming documentation"]}," to learn more about theming your Elements integration."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuring-elements-features","__idx":6},"children":["Configuring Elements Features"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"\n      features={{\n        globalFeatures: {\n          enabledShipEngineCarriers: [\n            'ups',\n            'stamps_com'\n          ]\n          enabledExternalCarriers: [\n            'apc',\n            'asendia',\n            'better_trucks',\n            'courierpost',\n            'dpd',\n            'seko',\n            'ups',\n            'yodel',\n          ],\n        },\n          purchaseLabelFeatures: { ... },\n          shipmentSummaryFeatures: { ... },\n          accountSettingsFeatures: { ... },\n          labelsGridFeatures: { ... }\n      }}\n","lang":"jsx"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"global-features","__idx":7},"children":["Global Features"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following properties are configured within the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["globalFeatures"]}," property."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Params"},"children":["Params"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enabledExternalCarriers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string[]"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," List external carrier codes for carriers that can be registered through the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/connect-external-carrier"},"children":["Connect External Carrier Element"]},". If this is omitted, external carriers cannot be registered. See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/getting-started#carriers-in-elements"},"children":["carriers section"]}," in the getting started guide for more information. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/account-settings/account-settings"},"children":["Account Settings Element"]}," or the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/account-settings/manage-external-carriers"},"children":["Manage External Carriers Element"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enabledShipEngineCarriers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string[]"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," List of ShipEngine carrier codes for carriers that can be registered through the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/connect-external-carrier"},"children":["Onboarding Element"]},". See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/getting-started#carriers-in-elements"},"children":["carriers section"]}," in the getting started guide for more information. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ** 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 ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/onboarding/onboarding"},"children":["Onboarding Element"]}," and will not be able to access the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/account-settings/carrier-services"},"children":["Carrier Services Element"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["poweredByShipEngine"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["boolean"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Enables the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Powered by ShipEngine"]}," logo in the footer various elements."]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Global features are set within the features parameter of the Elements SDK class constructor and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cannot"]}," be overridden within Element specific feature props."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"element-specific-features","__idx":8},"children":["Element specific Features"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Params"},"children":["Params"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseLabelFeatures"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string[]"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/label-workflow/purchase-label#purchase-label-features"},"children":["Purchase Label Features"]}," for a comprehensive list."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipmentSummaryFeatures"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string[]"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/label-workflow/shipment-summary#shipment-summary-features"},"children":["Shipment Summary Features"]}," for a comprehensive list."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountSettingsFeatures"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string[]"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/account-settings/account-settings#account-settings-features"},"children":["Account Settings Features"]}," for a comprehensive list."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["labelsGridFeatures"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string[]"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/label-workflow/labels-grid"},"children":["Labels Grid Features"]}," for a comprehensive list."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rendering-elements","__idx":9},"children":["Rendering Elements"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"elementscreateelement","__idx":10},"children":["elements.create(element)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Params"},"children":["Params"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["element"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," The name of the Element to be created."]}]}]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Elements:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountSettings"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrierServices"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connectExternalCarrier"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["labelLayout"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["labelWorkFlow"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["manageCarriers"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["manageExternalCarriers"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["manageFunding"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["manageWarehouses"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onboarding"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethodSettings"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseLabel"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipmentSummary"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionHistory"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unitSettings"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voidLabel"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["labelsGrid"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"elementsdestroy","__idx":11},"children":["elements.destroy()"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Removes Elements from the DOM and destroys it. A destroyed Element instance can not be re-activated or re-mounted to the DOM."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"elementsgetclient","__idx":12},"children":["elements.getClient()"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns an instance of the ShipEngine Elements API JavaScript client. This client can be used to interact directly with the ShipEngine API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If no parameters are passed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getClient()"]}," method to specify a different configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const token = await getToken();\nconst apiClient = elements.getClient(token, {\n  getToken,\n  onApiError: myOtherErrorHandler,\n});\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Args/Props"},"children":["Args/Props"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getToken"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["function"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," If defining your own API client configuration, the token callback function passed to the Elements SDK constructor must be included."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseURL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," A fully qualified domain name used as the base URL to route all API calls from the client."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Optional HTTP headers to be sent with all requests."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onApiError"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Callback function that will be executed whenever there is an error within the API."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"side-panel-methods-deprecated","__idx":13},"children":["Side Panel Methods (deprecated)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While working with the Elements SDK, you probably noticed methods for rendering individual Elements in a side panel. Methods like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onboardUser"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseLabel"]},", accessible via the Elements SDK class, have been deprecated in Elements v2 and will be removed in future versions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"element-render-methods","__idx":14},"children":["Element Render Methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways to render Elements in your application:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mounting elements in a specified DOM node or,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Opening the Elements in a pre-configured slide in drawer (Side Panel)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["440 to 800 pixels"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"elementmountdomelement-props","__idx":15},"children":["element.mount(domElement, props)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you mount an Element, you must create a container DOM element. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mount"]}," method attaches your Element to the DOM. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mount"]}]}," accepts either an ID Attribute (e.g., ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseLabelId"]}]},") or a DOM element as well as the Elements props. See the documentation for that Element for more information on its props."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To resolve this, we recommend applying specific CSS styles to the wrapper element where the Element is rendered:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"css","header":{"controls":{"copy":{}}},"source":".wrapper-class {\n  min-height: 100px; /* Ensures the wrapper has a minimum height to prevent collapsing */\n  max-height: 1000px; /* Prevents the wrapper from growing excessively */\n  overflow-y: scroll; /* Allows scrolling for content larger than the max-height */\n}\n","lang":"css"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Params"},"children":["Params"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["domElement"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string/DOM ELEMENT"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," The html ID or DOM element where your Element will be mounted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["props"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Props for the Element being mounted."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<div id=\"purchaseLabelId\">\n  <!-- Purchase Label Element will be inserted here. -->\n</div>\n\n<script>\n  purchaseLabel.mount('purchaseLabelId');\n</script>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"elementupdateprops","__idx":16},"children":["element.update(props)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Updates the props for the element"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Params"},"children":["Params"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["props"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Props for the Element being updated."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"// updates the shipment Id of the purchase label element\npurchaseLabel.update({ shipmentId: 'se-1198001' });\n","lang":"jsx"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"elementunmount","__idx":17},"children":["element.unmount()"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unmounts the Element from the DOM. Call the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["element.mount()"]}," method to re-attach it to the DOM."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"purchaseLabel.unmount();\n","lang":"jsx"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"elementrendersidepanelprops","__idx":18},"children":["element.renderSidePanel(props)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"props"},"children":["props"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["elementProps"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Props for the Element being updated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidePanelHeaderProps"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Props for the Element being updated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidePanelProps"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["object"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Props for the Element being updated."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"side-panel-props","__idx":19},"children":["Side Panel Props"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Args/Props"},"children":["Args/Props"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["header"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["ReactNode"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Component to use as the header of the component"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["footer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["ReactNode"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Component to use as the footer of the component"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["position"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Value indicating in which side of the screen the component should be placed. Either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["right"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["left"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Value indicating a predefined size. Either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["regular"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["large"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["containerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Id of the container from which the SidePanel will get the height and top"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBackdropClick"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["function"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," An optional async/sync callback to be executed when click is performed on the outside of the side panel"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applyBackdropToBody"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["boolean"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Flag to indicate if the backdrop should be placed inside the body"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"side-panel-header-props","__idx":20},"children":["Side Panel Header Props"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Args/Props"},"children":["Args/Props"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," Side panel title"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["closeButtonTooltip"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Text rendered inside the side panel close button tool tip."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["closeAriaLabel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Aria label for the close button"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onClickClose"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["function"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," Optional callback function invoked when the side panel close button is clicked"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"purchaseLabel.renderSidePanel({\n  elementProps: { shipmentId: 'se-11975001' },\n  sidePanelHeaderProps: { title: 'Purchase a Label' },\n  sidePanelProps: { position: 'left' },\n});\n","lang":"jsx"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"elementclosesidepanel","__idx":21},"children":["element.closeSidePanel()"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Closes the currently opened side panel."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"purchaseLabel.closeSidePanel();\n","lang":"jsx"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-shipments","__idx":22},"children":["Creating Shipments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const client = elements.getClient(await getToken());\nconst response = await client.shipments.create({\n  ship_to: {\n    name: 'Benjamin Biggs',\n    phone: '+44 44 4444 4444',\n    address_line1: \"Dean's Yard\",\n    city_locality: 'London',\n    postal_code: 'SW1P 3PA',\n    country_code: 'UK',\n  },\n  ship_from: {\n    name: 'John Doe',\n    company_name: 'Example Corp',\n    phone: '333-333-3333',\n    address_line1: '4301 Bull Creek Rd',\n    city_locality: 'Austin',\n    state_province: 'TX',\n    postal_code: '78731',\n    country_code: 'US',\n  },\n  packages: [\n    {\n      weight: { value: 20, unit: 'ounce' },\n      dimensions: { height: 6, width: 12, length: 24, unit: 'inch' },\n      products: [\n        {\n          description: 'Pizza',\n          quantity: 2,\n          value: {\n            currency: 'USD',\n            amount: 20,\n          },\n          sku: '1234ABCD',\n          harmonized_tariff_code: '1905.90.9060',\n          country_of_origin: 'US',\n        },\n      ],\n    },\n  ],\n});\n\nconst shipmentId = response.data.shipments[0].shipmentId;\n\nconst purchaseLabel = elements.create('purchaseLabel');\npurchaseLabel.renderSidePanel({\n  elementProps: {\n    shipmentId: this.shipmentId,\n  },\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_to"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_from"]}," properties are required; The rest may be left blank to be filled in by the user in the Element. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["packages.products"]}," array is used for Customs information, and is not generally required for local shipments."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information on the available fields within the Shipment object, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://shipengine.github.io/shipengine-openapi/#operation/create_shipments"},"children":["ShipEngine API documentation"]},". For additional functionality provided by the Elements API Client, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://elements-api-sdk-docs.shipengine.com/modules/_shipengine_js_api.html"},"children":["ShipEngine Elements API Clients documentation"]},"."]}]},"headings":[{"value":"Elements SDK","id":"elements-sdk","depth":1},{"value":"Quick Start","id":"quick-start","depth":2},{"value":"Install Peer Dependencies:","id":"install-peer-dependencies","depth":3},{"value":"Elements CDN","id":"elements-cdn","depth":3},{"value":"Initialize Elements","id":"initialize-elements","depth":2},{"value":"Initialization Parameters","id":"initialization-parameters","depth":4},{"value":"Configuring Elements Features","id":"configuring-elements-features","depth":2},{"value":"Global Features","id":"global-features","depth":3},{"value":"Element specific Features","id":"element-specific-features","depth":3},{"value":"Rendering Elements","id":"rendering-elements","depth":2},{"value":"elements.create(element)","id":"elementscreateelement","depth":4},{"value":"elements.destroy()","id":"elementsdestroy","depth":4},{"value":"elements.getClient()","id":"elementsgetclient","depth":4},{"value":"Side Panel Methods (deprecated)","id":"side-panel-methods-deprecated","depth":4},{"value":"Element Render Methods","id":"element-render-methods","depth":2},{"value":"element.mount(domElement, props)","id":"elementmountdomelement-props","depth":4},{"value":"element.update(props)","id":"elementupdateprops","depth":4},{"value":"element.unmount()","id":"elementunmount","depth":4},{"value":"element.renderSidePanel(props)","id":"elementrendersidepanelprops","depth":4},{"value":"Side Panel Props","id":"side-panel-props","depth":5},{"value":"Side Panel Header Props","id":"side-panel-header-props","depth":5},{"value":"element.closeSidePanel()","id":"elementclosesidepanel","depth":4},{"value":"Creating Shipments","id":"creating-shipments","depth":2}],"frontmatter":{"seo":{"title":"Elements SDK"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/elements/elements-sdk","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}