Stijltabellen (CSS) en JavaScript (JS) toevoegen aan een Drupal 8-thema

03/10/2025, by Ivan

Deze documentatie is bedoeld voor thema’s. Voor informatie over modules, zie Stijltabellen (CSS) en JavaScript (JS) toevoegen aan een Drupal 8-module.

In Drupal 8 worden stijltabellen (CSS) en JavaScript (JS) via hetzelfde systeem geladen voor zowel modules (code) als thema’s: asset libraries.

Ter verduidelijking: deze instructies zijn ALLEEN bedoeld voor thema’s en zijn niet van toepassing op modules.

Drupal volgt hierbij een belangrijk principe: assets (CSS of JS) worden enkel geladen als je expliciet aan Drupal meldt dat ze moeten worden geladen. Drupal laadt niet alle assets op elke pagina, omdat dat de prestaties van de gebruikersinterface zou verminderen.

Verschillen met Drupal 7

Er zijn zes belangrijke verschillen ten opzichte van Drupal 7:

Het bestand THEME.info.yml vervangt het bestand THEME.info (met dezelfde gegevens).
De property stylesheets (voor CSS) in THEME.info is verwijderd en vervangen door *.libraries.yml, waarbij `*` de naam van het thema of module is.
De property scripts (voor JS) in THEME.info is verwijderd en eveneens vervangen door *.libraries.yml.
Alleen de CSS/JS die nodig is op een pagina wordt geladen. jQuery wordt bijvoorbeeld niet langer automatisch geladen tenzij dit expliciet in *.libraries.yml staat. Als je thema jQuery of andere assets op elke pagina nodig heeft, moet je ze toevoegen aan *.libraries.yml en daarna de library in THEME.info.yml opnemen.
In Drupal 7 moesten libraries gedefinieerd worden met hook_library_info(). Dit is vervangen door *.libraries.yml.
In Drupal 8 zijn drupal_add_css(), drupal_add_js() en drupal_add_library() verwijderd ten gunste van #attached

Proces

Om CSS of JS-assets te laden:

Sla CSS of JS op in een bestand met de juiste naamconventies en bestandsstructuur.
Definieer een “library” die deze CSS/JS-bestanden in je thema registreert.
Koppel de library aan alle pagina’s, aan specifieke Twig-sjablonen of aan specifieke pagina’s via preprocess-functies.

Library definiëren

Alle libraries worden gedefinieerd in het bestand *.libraries.yml in de themamap. Als je thema “fluffiness” heet, moet het bestand fluffiness.libraries.yml heten. Elke library bevat een entry met de details van CSS- en JS-bestanden, bijvoorbeeld:

# fluffiness.libraries.yml
cuddly-slider:
  version: 1.x
  css:
    theme:
      css/cuddly-slider.css: {}
  js:
    js/cuddly-slider.js: {}

In dit voorbeeld staan de bestanden cuddly-slider.js en cuddly-slider.css in de mappen js en css van je thema.

Opmerking: er zijn veel meer opties mogelijk bij libraries, zie Libraries: parameters en details.

jQuery toevoegen

Drupal 8 laadt jQuery niet langer standaard. Als je library jQuery nodig heeft, moet je afhankelijkheid declareren van core/jquery:

cuddly-slider:
  version: 1.x
  css:
    theme:
      css/cuddly-slider.css: {}
  js:
    js/cuddly-slider.js: {}
  dependencies:
    - core/jquery

Afhankelijkheden

Declareer afhankelijkheden in de vorm namespace/library. Voorbeeld:

new_library:
  js:
    js/new_libary.js: {}
  dependencies:
    - core/jquery
    - my_module/my_library
    - my_theme/my_library

Library koppelen aan alle pagina’s

Gebruik meestal een global-styling library (CSS) en eventueel global-scripts (JS). Voeg deze toe aan info.yml van je thema.

libraries:
  - fluffiness/global-styling
  - fluffiness/global-scripts

Library koppelen via Twig-sjabloon

{{ attach_library('fluffiness/cuddly-slider') }}
<div>Some fluffy markup {{ message }}</div>

Library koppelen aan subset van pagina’s

Gebruik preprocess-functies, bijvoorbeeld:

function fluffiness_preprocess_maintenance_page(&$variables) {
  $variables['#attached']['library'][] = 'fluffiness/cuddly-slider';
}

Voor pagina’s op basis van route:

function fluffiness_preprocess_page(&$variables) {
  $variables['page']['#cache']['contexts'][] = 'route';
  if (\Drupal::routeMatch()->getRouteName() === "entity.node.preview") {
    $variables['#attached']['library'][] = 'fluffiness/node-preview';
  }
}

Meer details

Libraries kunnen eigenschappen hebben voor CSS- en JS-bestanden (attributes, browsers, media, preprocess, type, weight, enz.). Zie de documentatie voor alle opties.

Libraries overschrijven en uitbreiden

Gebruik libraries-override en libraries-extend in je info.yml om bestaande libraries te vervangen of uit te breiden. Bijvoorbeeld:

libraries-override:
  drupal/dialog:
    css:
      theme:
        dialog.theme.css: false

libraries-extend:
  core/drupal.user:
    - classy/user1
    - classy/user2

Externe libraries / CDN

Externe bestanden kunnen met type: external geladen worden, bv.:

font-awesome:
  remote: https://fortawesome.github.io/Font-Awesome/
  version: 4.5.0
  css:
    theme:
      https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css: { type: external, minified: true }

Extra Block Types (EBT) - Nieuwe Layout Builder ervaring❗

❗Extra Paragraph Types (EPT) - Nieuwe Paragraphs ervaring