Web Components | ShipPeek

Getting started

Install the package and start using components in under a minute.

Install

# npm
npm install @shippeek/components

# bun
bun add @shippeek/components

# yarn
yarn add @shippeek/components

Usage

These are standard web components - they work in any framework or plain HTML. Pick your stack below.

<script type="module" src="node_modules/@shippeek/components/dist/index.js"></script>

<shippeek-tracker
  tracking-number="794644790138"
  carrier="fedex"
  api-key="your-api-key"
></shippeek-tracker>

<shippeek-rates
  api-key="your-api-key"
  mode="ltl"
  request-json='{"originPostalCode":"90210","destPostalCode":"10001","items":[{"weight":500}]}'
></shippeek-rates>

import '@shippeek/components';

function TrackingPage() {
  return (
    <shippeek-tracker
      tracking-number="794644790138"
      carrier="fedex"
      api-key="your-api-key"
    />
  );
}

<script setup>
import '@shippeek/components';
</script>

<template>
  <shippeek-tracker
    tracking-number="794644790138"
    carrier="fedex"
    :api-key="apiKey"
  />
</template>

<script>
  import '@shippeek/components';
  let apiKey = 'your-api-key';
</script>

<shippeek-tracker
  tracking-number="794644790138"
  carrier="fedex"
  api-key={apiKey}
/>

TypeScript

For TypeScript projects using React, add type declarations for the custom elements.

declare namespace JSX {
  interface IntrinsicElements {
    'shippeek-tracker': any;
    'shippeek-rates': any;
    'shippeek-rate-card': any;
  }
}

Individual imports

Import only the components you need to reduce bundle size.

// Import everything
import '@shippeek/components';

// Or import individual components
import '@shippeek/components/shippeek-tracker';
import '@shippeek/components/shippeek-rates';
import '@shippeek/components/shippeek-rate-card';

Tracking Timeline <shippeek-tracker>

Displays a step-by-step tracking timeline for a shipment. Fetches data from the Shippeek API and updates automatically.

Example

Try it live

Connect to the Shippeek API with your credentials to fetch real tracking data.

Tracking number

Carrier

API key

Props

Attribute	Type	Default	Description
`tracking-number`	string	-	The tracking number to look up
`carrier`	string	-	Carrier code (e.g. fedex, ups)
`api-key`	string	-	Your Shippeek API key
`api-url`	string	`https://api.shippeek.com`	Base API URL
`demo`	boolean	`false`	Render with sample data (no API call)

Rate Comparison <shippeek-rates>

Sortable rate table that fetches LTL or parcel rates from multiple carriers. Click a row to select it.

Example

Click a row to fire the shippeek-rate-selected event

Try it live

Fetch rates from the Shippeek API. Uses a sample request body (90210 to 10001, 500 lbs, class 70).

Mode

API key

Props

Attribute	Type	Default	Description
`api-key`	string	-	Your Shippeek API key
`api-url`	string	`https://api.shippeek.com`	Base API URL
`mode`	"ltl" \| "parcel"	`ltl`	Rate mode
`request-json`	string (JSON)	-	JSON-stringified rate request body
`demo`	boolean	`false`	Render with sample data (no API call)

Events

Event	Detail	Description
`shippeek-rate-selected`	CarrierRate	Fired when a user clicks a rate row

Rate Card <shippeek-rate-card>

Presentational card for a single rate with charge breakdown. No API calls - pass a rate object via rate-json.

Example

Props

Attribute	Type	Default	Description
`rate-json`	string (JSON)	-	JSON-stringified CarrierRate object

Customization

Override CSS custom properties to match your brand. All components inherit from these tokens.

Design tokens

Token	Default	Description
`--sp-color-accent`	#303030	Primary / accent color
`--sp-color-bg`	#ffffff	Component background
`--sp-color-surface`	#f7f7f7	Surface / subtle background
`--sp-color-text-primary`	#303030	Primary text
`--sp-color-text-secondary`	#616161	Secondary text
`--sp-color-border`	#e3e3e3	Border color
`--sp-color-success`	#047b5d	Success / delivered
`--sp-color-error`	#e22c38	Error / exception
`--sp-radius`	12px	Border radius
`--sp-font`	Inter, system	Font family