Skip to content

Tips & Tricks

Choosing the Right PostNL Type

The card supports three PostNL variants. Use the table below to pick the right one.

Situation Use type
Fresh install, ha-postnl ≥ 4.0.0 postnl_v4
Existing install, ha-postnl ≤ 3.x postnl
Using arjenbos/ha-postnl postnl_legacy

Tip

If you upgrade from peternijssen/ha-postnl v3.x to v4.x, change type: postnl to type: postnl_v4 in the card configuration. Your sensor entity IDs stay the same — only the card type needs to change.

Sensors Without a Username Prefix

Some PostNL 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_v4
    user: ""

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

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 do not use DHL, DPD or GLS, or do not send parcels, you can hide the tabs you don't need:

show_sent: false
show_letters: false

GLS Postal Codes

GLS has no login/account concept — the user field is the postal code of your local GLS hub instead, e.g. 1234ab. Type it with or without a space (1234 AB also works — it's sanitised automatically); GLS has no Sent tab since there's no sender/account to track outgoing parcels against.

Using PHU Carrier Icons

If you have custom-brand-icons installed via HACS, the card automatically uses branded carrier icons (phu:postnl, phu:dhl, phu:dpd). No configuration is needed — icons are resolved at render time.

Multiple Cards for Different Purposes

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

# Active deliveries card
type: custom:hki-parcels-card
title: Onderweg
show_delivered: false
show_sent: false
show_letters: false
carriers:
  - type: postnl_v4
    user: my_account

# History card
type: custom:hki-parcels-card
title: Ontvangen
show_delivered: true
show_sent: true
days_back: 30
show_animation: false
show_placeholder: false
carriers:
  - type: postnl_v4
    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"

Delivered Outgoing Parcels (Verzonden → Bezorgd)

The Sent tab has two sections: Still in transit and Delivered. The Delivered section requires the sensor.*_postnl_outgoing_delivered_parcels sensor, which is available in peternijssen/ha-postnl ≥ 4.3.1.

If the sensor is present, it is picked up automatically. If the Delivered section remains empty after upgrading ha-postnl, verify the sensor exists in Developer Tools → States and check that entity_outgoing_delivered is not overridden with an incorrect value.

Reordering Card Sections

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

layout_order:
  - animation
  - header
  - tabs
  - list