Getting started

The Europa Component Library is a design system defining the visual identity of the European Commission on the web.

It provides design guidelines and code to help users create consistent and accessible web presence.

All library elements are accompanied by:

  • documentation explaining what the component is intended for and how it should be used
  • a visual demonstration of the component
  • HTML/CSS code for implementation

New components are continuously being added to the library. The team is also constantly updating visual guidelines for designers in the Guidelines section, where we provide detailed information about design principles and resources.

How to use ECL

ECL distributes its resources in different ways and depending on the implementation approach, things might change a bit: generally speaking, given the HTML markup defined by ECL, applying the distrbuted css and javascript on top of it would ensure the expected look and feel.

ECL resources are represented by:

  • css
  • javascript
  • icons (svgs and sprite)
  • logos (svgs)

Presets

All these resources are distributed in a single "package", called preset-ec, this package can be retrieved on npm or alternatively from the github release page as a zip file.

Using npm: npm install @ecl/preset-ec OR yarn add @ecl/preset-ec

Once you have the preset-ec you're ready to setup the ECL integration in your application or website like this:

<!doctype html>
<html lang="en" class="no-js">
  <head>
    <meta charset="utf-8" />
    <title>Page title</title>
    <meta content="width=device-width,initial-scale=1" name="viewport" />
    <meta content="IE=edge" http-equiv="X-UA-Compatible" />
    <script>
      var cl = document.querySelector('html').classList;
      cl.remove('no-js');
      cl.add('has-js');
    </script>
    <script
      src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.29.1/moment.min.js"
      crossorigin="anonymous"
    ></script>
    <link
      rel="stylesheet"
      href="/styles/optional/ecl-reset.css"
      media="screen"
    />
    <link rel="stylesheet" href="/styles/ecl-eu.css" media="screen" />
    <link rel="stylesheet" href="/styles/ecl-eu-print.css" media="print" />
  </head>
  <body>
    <!-- content of your page here -->

    <script src="/scripts/ecl-eu.js"></script>
    <script>
      ECL.autoInit();
    </script>
  </body>
</html>

This assumes your preset-ec package is directly accessible in the root of your project, change the path according to your environment.

In this example the main ECL css and js are defined and in addition a css for print and the reset css are added.

There are also other optional css files distributed that can be used, moment.js is added because it's needed for the ECL datepicker, see below for further information.

Using the CDN

ECL is also distributing its presets on a CDN, all the files distributed in the package mentioned before are also available there, this is the pattern to reach them: https://cdn{1,2,3 or 4}.fpfis.tech.ec.europa.eu/ecl/{tag}/{system}/{path/to/the/asset}

Ex: https://cdn1.fpfis.tech.ec.europa.eu/ecl/v3.9.1/ec/styles/optional/ecl-ec-default.css

Download a preset-ec package from the release page to see all the files available so to know how to reach them in the CDN, the file system is the same.

For more security, use the SRI hashes corresponding to the files when using them from the CDN. They can be found in the release page, in a json file, but here are the most common ones:

SRI hashes (click to expand)

  • for ecl-eu.css: n/a

  • for ecl-eu-print.css: n/a

  • for ecl-eu.js: n/a

When using the CDN for icons and logos be aware that it's not possible to serve svgs from an external domain without using some workaround, see the "Additional information" below.

For different reasons, starting from performances and network traffic, the recommended way of using ECL is to fetch its resources for then hosting them in the same domain where they are going to be used.

Optional styles

There are several optional CSS files, located in ec/styles/optional, which can be included in your site on not, depending on the needs.
These optional CSS have to be called before the main ECL CSS

  • ecl-reset.css: contains some css reset rules, mostly based on normalize.css, with a few custom additions
  • ecl-ec-default.css: apply ECL styling to some default HTML tags (links, buttons, table, ...). Note that this file is meant to be used in specific cases, the recommanded way to use ECL is still to add corresponding classes to HTML elements. A corresponding print css ecl-ec-default-print is also provided.

JavaScript

You can either initalise JS components manually or automatically. Here, we will focus on the automatic initialisation. If you want to know more about the manual initialisation, please check the component's documentation.

In order to automatically initialize a component, add data-ecl-auto-init="[component class]" to the root element of the component, [component class] being the name of the JS class related to the component.

For example, if you want to auto initialize a Message:

<div
  role="alert"
  class="ecl-message ecl-message--info"
  data-ecl-message
  data-ecl-auto-init="Message"
>
  ... Message component ...
</div>

Then, in the footer of the document (or whenever the document is ready), call ECL.autoInit(). For example:

  <body>
    ...
    <script>
      ECL.autoInit();
    </script>
  </body>
</html>

moment.js

As explained in a more technical language in the datepicker api page ECL uses Pikaday which requires moment.js and this library is not bundled by ECL. Therefore moment.js needs to be loaded or bundled by the application or website using ECL, depending on the needs.

Additional information

  • to integrate ECL components, copy the markup from the component you want and paste it in the <body>. This markup can be found on this website and on the playground. TWIG templates are also provided on npm for easy integration.
  • make sure that you are correctly loading the icons and the logo by using the right paths. You will usually find these assets under the /images folder of the preset you're using. We advise you to host the SVG sprites on the same domain as your website in order to avoid the Unsafe attempt to load URL kind of errors. If you still want to use the SVG sprite from the CDN, you can use svg4everybody and initialize it with: svg4everybody({ polyfill: true });.
  • before going live, make sure to embed the Cookie Consent Kit.
  • all useful information concerning releases content can be found on the release page

More on the available packages

ECL is distributed primarily as npm packages and this is the recommended way of getting it. When used in a node project this is surely the easiest and more reliable way, the new versions can be automatically detected and fetched and the ECL resources could be even rebuilt on the client side by fetching all the needed packages one by one.

Identifying the packages (click to expand)

In every release, starting from 3.9.1, a file containing a list of all the available packages on npm is deployed on the github release page, this list is quite long and you don't surely need, in a normal situation, to know all the available packages as you don't need to fetch them all.

ECL releases npm packages for:

  • builder (used to compile css and js) @ecl/builder
  • presets (EC and EU) @ecl/preset-ec
  • vanilla components (css and js) @ecl/vanilla-component-{name}
  • twig components (twig template) @ecl/twig-component-{name}
  • spec packages (data used in the demos) @ecl/specs-component-{name}
  • resources packages @ecl/resources-ec-{name}

Guidelines

Additional ready-to-use resources: