Getting started

What is the Europa Component Library?

The Europa Component Library (ECL) is the official design system for the European Commission's digital presence. It provides a comprehensive set of design guidelines, reusable components, and code resources to help teams create consistent, accessible, and user-friendly web experiences across Commission services.

Why use ECL?

Consistency: ECL ensures visual and functional consistency across all European Commission digital properties, strengthening the Commission's identity and improving user recognition.

Accessibility: All components are built following WCAG AA standards, ensuring your digital services are accessible to all users, including those with disabilities.

Efficiency: Pre-built, tested components significantly reduce development time and effort, allowing teams to focus on unique features rather than rebuilding common UI elements.

Maintainability: Centralized design system means updates and improvements benefit all projects using ECL, reducing long-term maintenance costs.

Compliance: Using ECL helps ensure alignment with European Commission digital service standards and branding requirements.

What does ECL provide?

  • Usage guidelines explaining when and how to use the components
  • Interactive demonstrations showing the components in action
  • Production-ready code including HTML markup, CSS styles, and JavaScript behavior
  • Design specifications for designers working in design tools
  • Accessibility documentation detailing compliance and best practices

The library is continuously evolving, with new components added regularly and existing components refined based on user feedback and changing needs.

For Developers

Installation

ECL is distributed as a bundled package called a preset, which includes all the CSS, JavaScript, and assets (logos, ...) needed to build European Commission-styled websites and applications.

Option 1: Package Manager (Recommended)

Install via npm or pnpm:

npm install @ecl/preset-ec

or

pnpm install @ecl/preset-ec

Benefits: Easy version management, seamless updates, and the ability to rebuild resources if needed.

Option 2: CDN

Load ECL resources directly from the CDN:

https://cdn{1,2,3,4}.fpfis.tech.ec.europa.eu/ecl/v{version}/ec/{path-to-asset}

Example:

Important: When using the CDN, always include Subresource Integrity (SRI) hashes for security. These can be found in the release notes for each version.

Common SRI hashes (click to expand)

  • ecl-ec.css: sha256-weUneFSjn83jJCX8p6SXkiL7O/ELJ5qjeHkXVBvp9tc= sha384-J/bNUgAqQHSiGdPSEtoRzFWccxz/UGACbztsM22NqLMIEkaPz47XREsCYpsHXFn7 sha512-QDa31gfjTve9qnQmLnhstL+wQY04J5bWaR/FX1sKD3FGUN15Gh7qBht+4cFV9Fy+aDXjeZo8NQDjijxZJqZKiA==

  • ecl-ec-print.css: sha256-v897WX34kjWN1/2YynPS+E+hfBAlCJ9J10XHBEYjpxk= sha384-JZSRDhfHysSLH8qJEstmeurB7J1P5pSqH0pSBfebqxKeN4HRGNU4n9GrT61c7cUB sha512-i31c295GDofnToKn8TyZGoKGjHirJX2L26gfvqXsa6XtL2Z97vu219idnlUHZzjPjvurXHs+q5VM07J5Nk64Uw==

  • ecl-ec.js: sha256-S2awITcVb/6aj3/wbDSx41Y2JQ/bH/ONG5jRlXnsbtQ= sha384-j9gQRIypkcg2UTTkuHR3ZU4Z9XhGZRmImxpfdRuy26MCcEH3mpC67NGMeMrM7j6z sha512-4QxgWbr72Do4fwpUojgwZeHnBxvKKHIHN/2sMqxhYVuoHvBm7H3VxD/BDOL+mvHvT1ZfHLlSpzXI/pCfjbahhQ==

  • ecl-esm-ec.js: sha256-DhPET1QBCs3DpHA9HXoKI7FjJtiGGiVkkR/FTyl3Icg= sha384-a+1N3mU7/YVqxShsJ31LWkD0uWdwx21cJDHSS0+/gnRTJeewZq4JX+qcPxMDu3nI sha512-oqybEY4D9vIe0lbFEYErx2egrbhJvpVJAVzk9+3seNM2nDiiNUn2BLCZ3FFYpLNqctPKz0iO0xZ7mVpTshwTOA==

<!-- CSS -->
<link
  rel="stylesheet"
  href="path-to-ecl-ec.css"
  integrity="sha256-... sha384-... sha512-..."
  crossorigin="anonymous"
  media="screen"
/>

<!-- JavaScript -->
<script
  type="module"
  src="path-to-ecl-esm-ec.js"
  integrity="sha256-... sha384-... sha512-..."
  crossorigin="anonymous"
></script>

Note: While the CDN is convenient, hosting ECL resources on your own domain is recommended for better performance, reduced network dependencies, and to avoid cross-origin issues with SVG assets.

Option 3: Direct Download

Download the preset package as a zip file from the GitHub releases page.

Basic Setup

Once you have the ECL preset, integrate it into your HTML pages:

<!doctype html>
<html lang="en" class="no-js">
  <head>
    <meta charset="utf-8" />
    <title>Page title</title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />

    <!-- Enable JavaScript detection -->
    <script>
      document.documentElement.classList.remove('no-js');
      document.documentElement.classList.add('has-js');
    </script>

    <!-- ECL Styles -->
    <link
      rel="stylesheet"
      href="/styles/optional/ecl-reset.css"
      media="screen"
    />
    <link
      rel="stylesheet"
      href="/styles/optional/ecl-ec-utilities.css"
      media="screen"
    />
    <link rel="stylesheet" href="/styles/ecl-ec.css" media="screen" />
    <link rel="stylesheet" href="/styles/ecl-ec-print.css" media="print" />
  </head>

  <body>
    <!-- Your page content here -->

    <!-- ECL JavaScript -->
    <script type="module" src="/scripts/ecl-esm-ec.js"></script>
    <script>
      ECL.autoInit();
    </script>
  </body>
</html>

Key points:

  • Adjust file paths based on where you've placed the preset files in your project
  • The no-js / has-js class toggle enables CSS to adapt based on JavaScript availability
  • The ECL object is globally available (on window)

Optional Styles

ECL provides several optional CSS files in the styles/optional/ directory. These must be included before the main ECL stylesheet if you choose to use them:

ecl-reset.css

Provides CSS reset rules based on normalize.css with Commission-specific additions. Recommended for new projects to ensure consistent cross-browser styling.

ecl-ec-default.css

Applies ECL styling to standard HTML elements (links, buttons, tables, etc.) without requiring specific classes. Useful for content-heavy sites, but the recommended approach is to use ECL classes explicitly for better control.

A corresponding print stylesheet ecl-ec-default-print.css is also available.

ecl-ec-utilities.css

Contains utility classes for spacing, typography, display, and more. Useful for quick styling adjustments without writing custom CSS.

ecl-ec-color-modes.css

Contains CSS definitions for the color modes system, enabling theme variations and customization. See the Colours documentation for more information.

JavaScript Components

ECL components can be initialized either automatically or manually.

Automatic Initialization (Recommended)

Add the data-ecl-auto-init attribute to any component's root element, specifying the component class name:

<div
  role="alert"
  class="ecl-notification ecl-notification--info"
  data-ecl-notification
  data-ecl-auto-init="Notification"
>
  <!-- Notification component content -->
</div>

Then call ECL.autoInit() once the DOM is ready (typically at the end of <body>):

<script type="module" src="/scripts/ecl-esm-ec.js"></script>
<script>
  ECL.autoInit();
</script>

All components with data-ecl-auto-init will be automatically initialized.

Manual Initialization

For more control, you can initialize components programmatically. See individual component documentation for specific APIs and initialization options.

Checking Your ECL Version

To verify which version of ECL you're using, open your browser's developer console and run:

ECL.version;

Icons

Icons are provided through the Webtools service and may require additional configuration. For the most up-to-date information and advanced usage, consult the Webtools documentation:

https://webtools.europa.eu/showcase/demo/?comp=icons&section=about&demo=how_to_use

Tooltip

ECL's tooltips can be enabled by adding a data-ecl-auto-init="Tooltip" attribute to a container in the page, like the body. All the elements containing a data-ecl-tooltip or a data-ecl-tooltip-inverted will have their tooltip associated, it will grab its content from the data attribute or alternatively from the title attribute.

Datepicker

ECL's datepicker component is based on the Duet Date Picker library. This library is not bundled with ECL, so you need to include it yourself if you use datepicker components.

Option 1 — Load from CDN (simplest, no Node required)

Important

Before using a resource from an external CDN, you have to make sure that this is allowed for your website. For instance, this is not the case for most of the websites hosted under europa.eu. So, even if this solution is the easiest to put in place, it may not be suited in your situation.

If you don't have restrictions on loading external scripts, you can include the datepicker directly by using:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@duetds/date-picker@1.4.0/dist/duet/duet.esm.js"
></script>

This will work on any page without installing Node or copying files manually.

Option 2 — NPM + bundler (recommended if you have a build process)

  1. Install the package:
npm install @duetds/date-picker
# or
pnpm add @duetds/date-picker
  1. Import or bundle it in your build process:
import '@duetds/date-picker/dist/duet.esm.js';

Option 3 — Manual copy for static pages or CMS

  1. Install the package (or skip if you already have it):
npm install @duetds/date-picker
  1. Copy the dist folder contents to a location your webserver can serve, for example:
cp -r node_modules/@duetds/date-picker/dist/* /path/to/assets/duet/
  1. Include the library in your HTML pages that use datepickers:
<script type="module" src="/assets/duet/duet.esm.js"></script>

Option 4 — Download tarball from the npm registry (no Node required)

  1. Download the tarball:
wget https://registry.npmjs.org/@duetds/date-picker/-/date-picker-1.4.0.tgz
  1. Extract it:
tar -xzf date-picker-1.4.0.tgz
  1. Copy the dist folder contents to a location your webserver can serve:
cp -r package/dist/* /path/to/assets/duet/
  1. Include the library in your HTML pages that use datepickers:
<script type="module" src="/assets/duet/duet.esm.js"></script>

Notes

  • The /assets/duet/ folder must contain the files from dist/, not the dist folder itself.
  • Only include the <script> on pages that actually use datepickers.
  • Option 2 is recommended for modern build setups and avoids manual copying.
  • Option 1 is the simplest, but only if external scripts are allowed.
  • Option 4 is useful for static sites or CMSs where Node.js/npm is not available.

Right-to-Left (RTL) Support

ECL components support right-to-left languages (Arabic, Hebrew, etc.). To enable RTL display, add the dir="rtl" attribute to your HTML document:

<html lang="ar" dir="rtl"></html>

or

<body dir="rtl"></body>

The direction attribute can be set on any parent element. Without dir="rtl", ECL will default to left-to-right display.

Browser Support

ECL supports all modern, evergreen browsers:

  • Chrome, Edge, Firefox, Safari (latest versions)
  • No Internet Explorer support

ECL uses modern web standards including CSS Grid, Flexbox, CSS Custom Properties, and ES6+ JavaScript (transpiled for broader compatibility).

Accessibility

All ECL components are built to meet WCAG 2.1 Level AA accessibility standards. This includes:

  • Semantic HTML structure
  • Proper ARIA attributes
  • Keyboard navigation support
  • Screen reader compatibility
  • Color contrast compliance

For component-specific accessibility details, refer to each component's documentation.

Integration Tips

Using ECL Components

To integrate ECL components in your pages:

  1. Find the component you need in the Components section
  2. Copy the HTML markup from the component documentation or playground
  3. Paste it into your page where needed
  4. Customize the component, if needed, by modifying data attributes, classes, or content

Twig Templates

For server-side rendering, ECL provides Twig templates for all components, available on npm:

npm install @ecl/{component-name}

Templates are usually called {component-name}.html.twig

Browse available packages on npm.

Logo and Asset Paths

Ensure logos and other assets load correctly by verifying file paths. Assets are typically located in the /images/ folder of your preset.

Recommendation: Host all ECL assets (CSS, JS, logos) on your own domain to avoid CORS issues and improve load times.

Before Going Live

  • Cookie Consent: Implement the Cookie Consent Kit as required for Commission sites
  • Accessibility testing: Validate your implementation with screen readers and automated accessibility tools
  • Cross-browser testing: Verify functionality across different browsers and devices
  • Performance: Optimize asset loading (compression, caching, lazy loading where appropriate)

Additional Resources

Explore more about designing and building with ECL:

For release notes, changelogs, and downloads, visit the GitHub releases page.