For developers
The DHL User Interface Library is a rapidly growing collection of 70+ React, Vue, and Angular components ready to be used out of the box. As a developer, you can quickly import, configure and use the components you need to build your projects.
Add access token before you begin
The DHL User Interface Library is a private package for DHL digital services and requires an npm access token. Contact Dennis Appelrath to get access token.
The npm access token must be kept safe: it is a secret not to be shared or stored in cleartext.
Adding the token
To enable installation and local development, add the token to your
.npmrc file.
@dhl-official:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${DUIL_NPM_TOKEN}
For guidance on how to use the
.npmrcfile, see the .npmrc FAQ section.
Installation
The DHL User Interface Library provides five packages for project integration since it version 2.4.0 — three framework-specific (Angular, React, Vue) and two framework-agnostic (icons and tokens). Starting from version 2.10.0, two additional packages are available for React and Vue. The new additions allow for a single bundle javascript approach without lazy loading and for a total count of seven available packages.
Our tech stack
The DHL User Interface Library uses the following technology stack to deliver the library:
- Stencil – A compiler that generates Web Components and framework wrappers
- Lerna – A tool for managing multiple packages within a single repository (monorepo pattern)
- Docusaurus – A static site generator for building documentation websites
- Storybook – A tool for developing UI components in isolation
- TypeScript – A superset of JavaScript that enables type safety
- Jest & Puppeteer – A JavaScript testing framework for unit and integration testing
- GitHub Actions – A CI/CD platform to automate software workflows
Explore DUIL library
Components
Browse our library of 70+ web components. Access documentation, copy-paste code snippets, and view integration guides for React, Angular, and Vue.
Guidelines & foundations
Understand the structure and design tokens that power DUIL. Learn about our variables for typography, spacing, and colors to build consistent on-brand UIs.
Do you have any questions?
Installation & onboarding
The DHL User Interface Library packages are private and published to npm. To
install them, create a .npmrc file in your project root with the following
configuration:
@dhl-official:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${DUIL_NPM_TOKEN}
Before running npm install, ensure you have set the DUIL_NPM_TOKEN
environment variable to your access token.
Keep the token in an environment variable. Do not put the token itself in
.npmrc or commit it to source control.
For additional configuration options, refer to the official npmrc documentation.
Do I need separate npm tokens for different packages (like Icons, Tokens), application pipelines, or team members?
No, you do not need separate tokens. We issue one single npm token per application. This means the same token can be used to download all packages or shared across all developers on your team.
What happens when npm token expires, and how do I renew it?
Once your npm token expires, you will no longer be able to download or update any of the library packages. This will also cause any pipelines utilizing the expired token to fail.
To request a new token or renew an existing one, you can:
- Submit a request via our homepage.
- Reach out to Dennis Appelrath or the design system team in our Microsoft Teams channel.
- Reach out to development team member via private messages in Microsoft Teams.
Can I install DUIL via Artifactory? Why do I need an npm token?
Currently, using an npm token is the only officially supported installation method for DUIL. While the library might be accessible via Artifactory, we do not officially support that route and cannot guarantee you will receive the latest version.
We're aware some teams use Artifactory and are investigating official support. If this applies to you, please let us know so we have visibility into adoption.
To align with DHL's internal tooling strategy, we are also evaluating a future transition from NPM to GitHub Packages.
Why does the installation fail with a "package not found" or non-existence error?
This error typically occurs for one of three reasons:
- Incorrect .npmrc configuration: Verify that your .npmrc file is properly set up in your project's root directory.
- Expired npm token: If your token has expired, package pulls will be rejected.
- Using Artifactory: Attempting to pull the library via Artifactory will fail, as this is not an officially supported installation method.
Which specific versions of React, Angular and Vue does the library currently support?
The library currently supports the following framework versions:
- React: v19+
- Angular: Up to v21
- Vue: v3+
Yes. TypeScript is fully supported out of the box.
Implementation & customization
Many of the components in our documentation include ready-to-use React code snippets. Additionally, you can explore interactive examples for all DUIL components in our Storybook.
Can I use DUIL alongside other UI libraries (like MUI, Shadcn, Chakra UI, etc.)?
Technically, yes, you can if your project strictly requires it. However, we highly recommend against using multiple component libraries in a single application.
Please review our Dark Theme implementation guide for detailed, step-by-step instructions on how to set it up in your application.
Not yet, but this is in development and will be available soon.
Yes, you can apply Tailwind CSS utility classes directly to our components
by passing them through the className and dataClassName props.
Yes. If you need to override default styles or add specific CSS, you can
utilize the dataClassName prop available on our components to safely
apply your own custom styling.
Support, troubleshooting & contributions
When a component is missing, should I build a custom solution or submit a feature request?
We encourage you to submit a feature request first! Please join our Microsoft Teams community and submit your request publicly. Our team can let you know if the component is already on our roadmap or advise you on building a temporary custom solution for your immediate project needs. This also helps us track system needs transparently and allows other designers to weigh in if they have similar use cases.
How do I report a bug, and what is the prioritization process for delivering fixes?
You can report bugs directly in our official Microsoft Teams channel.
Once a bug is reported, we prioritize fixes based on the severity of the issue. Our team will conduct an initial analysis and follow up with you regarding the status — typically within 24 to 48 hours.
We actively encourage contributions to help the design system grow! If you have built a component that would benefit the wider team, you can propose your contribution in our Microsoft Teams community.
To request a new component or icon, please join our Microsoft Teams community and submit your request publicly. This helps us track system needs transparently and allows other designers to weigh in if they have similar use cases.
Can external developers outside the DHL Group use the library?
Yes, and we strongly encourage it. External developers working on DHL projects should consume DUIL to stay aligned with company strategy. As our single source of truth, DUIL guarantees that all applications remain perfectly consistent and brand-compliant regardless of who builds them.
How do I handle discrepancies between Figma properties and the available props in a coded component?
Please report it to the DUIL team through any of our support channels (Microsoft Teams, GitHub, email, or chat). We will review the issue and ensure the design and code are properly aligned.
Releases & versioning
How often do you update the library, and how often should I update?
We release updates regularly: minor updates and patches arrive roughly every 2–4 weeks, while major versions are released less frequently as needed.
We recommend updating to the latest version as soon as it is convenient. For major version upgrades, we suggest planning those within 2–3 months of release. Always check our changelog to see what's new before upgrading.
We officially support the current major version and the one immediately prior. Older versions may still work, but they will not receive bug fixes, security patches, or deeper implementation support.
If you run into any blockers during an upgrade, please contact us directly!
Architecture & compatibility
Does DUIL support WebComponents or mobile frameworks like React Native?
We do not currently support WebComponents or mobile frameworks like React Native, but support for these is on our roadmap and coming soon!
Can I consume only the design tokens if I am not using a framework like React or Angular?
Yes, absolutely! You can consume our design tokens independently of any specific framework. Please follow the instructions in our Tokens installation guide to get started.
Can I use an AI model or MCP server to generate my project using DUIL components?
Not yet, but we are actively exploring this space and planning to run a PoC. If your team is interested in AI integration or already experimenting with it, please reach out to us directly — we would love to hear about your specific use case.