Skip to content

Tips & Tricks

Sensors without a username prefix

Some setups create sensors without a username prefix, for example sensor.postnl_incoming_parcels instead of sensor.john_postnl_incoming_parcels. In this case, leave the user field empty:

carriers:
  - type: postnl
    user: ""

The editor's auto-detection also handles this case automatically.


Registering a parcel without opening the integration

For every carrier with "Add parcel from card" in the Carrier types table, use the "Add parcel" control at the bottom of the card instead of switching to the integration's own Configure dialog — it calls the same track_parcel service directly, so the parcel shows up in the card immediately. See Add parcel support for why account-based carriers such as PostNL, DHL NL, DPD and Vinted Go don't need it.


Naming a parcel

Open a parcel's detail panel and click "Add name" to give it a short label of your own — "Birthday gift" is a lot easier to spot than a bare tracking code. By default (custom_name_scope: everyone) the name is saved instance-wide with live updates for every Home Assistant user — adding or editing one requires an admin account, though everyone can see the names. Set custom_name_scope: me to save it to your own Home Assistant account instead (synced across your own devices only), device to keep it in this browser only, or off to hide the control entirely.


Changing how parcels are sorted and grouped

By default, In Transit and Sent show the soonest-arriving parcel first within each carrier's own section (Delivered shows the most recent first), and carrier sections aren't in a fixed order — whichever carrier's next parcel is soonest shows first. Set group_by_carrier: false for one flat list instead, where parcels from different carriers interleave directly by date rather than being grouped — e.g. a PostNL parcel, then two DHL parcels, then three more PostNL parcels, purely in delivery-time order. Set sort_order: newest_first or oldest_first to pin one fixed direction everywhere instead of the automatic soonest/most-recent split.


Limiting the history period

Use days_back to control how far back delivered parcels are shown. A shorter period keeps the Delivered tab manageable.

days_back: 7   # Show only the last 7 days

Hiding unused tabs

If you don't send parcels, or don't use PostNL, you can hide the tabs you don't need:

show_sent: false
show_letters: false

Opening the card on a tab from a notification

The card normally opens on In transit. Set default_tab to start elsewhere:

default_tab: post   # in_transit, delivered, sent or post

A dashboard link can choose the tab as well, by adding ?parcel_tab= to the dashboard's URL. That wins over default_tab, which makes it handy for a notification: tapping it opens the card straight on the Letters tab, also when the dashboard is already open.

action: notify.mobile_app_your_phone
data:
  title: "You've got mail"
  message: "A new letter is on its way."
  data:
    clickAction: /dashboard-home/parcels?parcel_tab=post   # Android
    url: /dashboard-home/parcels?parcel_tab=post           # iPhone

Replace /dashboard-home/parcels with the path of the dashboard view that holds the card. A tab that is hidden or doesn't exist (for example post without a letters entity) is ignored, and the card opens on its usual tab.


Zooming into a letter

Tap a letter's scan to open it. Pinch or double-tap to zoom in (scroll or double-click on a desktop), and drag to move around the zoomed scan.


Using the carrier overview popup

With two or more carriers configured, click any logo in the combo banner to see everything for that carrier — In Transit, Delivered, Sent and Letters — in one popup, without switching tabs. It's a quick way to check "has anything from GLS shown up yet?" without hunting across every tab.


Showing the carrier's own status text

By default the card shows a generic translated status ("In transit", "Delivered", ...) so every carrier reads the same. Set show_raw_status: true to show each carrier's own status text instead (e.g. GLS's "Onderweg - geladen voor aflevering") when the integration provides one — falls back to the generic label for any parcel without one.

show_raw_status: true

Using PHU carrier icons

If you have custom-brand-icons installed (from the Marketplace or HACS), the card automatically uses branded carrier icons where available. No configuration is needed. SVG scene logos are loaded once and cached; if PHU is absent or the installed version lacks an icon, the scene uses the existing carrier logo instead. A custom carrier without a logo gets a plain panel in its configured colour. See Installation for the released mappings.


Multiple cards for different purposes

Consider using two separate cards: one focused on active deliveries and one showing history.

# Active deliveries card
type: custom:ha-parcel-card
title: Onderweg
show_delivered: false
show_sent: false
show_letters: false
carriers:
  - type: postnl
    user: my_account

# History card
type: custom:ha-parcel-card
title: Ontvangen
show_delivered: true
show_sent: true
days_back: 30
show_animation: false
show_placeholder: false
carriers:
  - type: postnl
    user: my_account

Colour theming

Use CSS variables for colours that automatically adapt to your Home Assistant theme:

header_color: "var(--primary-color)"
header_text_color: "var(--text-primary-color)"

Or use explicit hex values for a fixed colour scheme:

header_color: "#1a1a2e"
header_text_color: "#e0e0e0"

Reordering card sections

Change the visual order of the header, animation, tabs and list sections:

layout_order:
  - animation
  - header
  - tabs
  - list