Change record status: 
Project: 
Introduced in branch: 
8.x
Description: 

-------
For those looking to remove or replace CSS files, see libraries-extend and libraries-override. https://www.drupal.org/theme-guide/8/assets#override-extend
-------

Note: This has been further changed, see https://www.drupal.org/node/2473869

Prior to Drupal 8, there was a single stylesheets[] property for theme .info files, which allowed to

  • add new CSS files of a theme or base theme
  • override (replace) CSS files that were previously added by a module or base theme in a theme
  • remove CSS files of a module or base theme

The baked-in facility to override and remove CSS files was partially broken in that it caused the replacement CSS files to be loaded in a different order/position than the original, and all other meta/loading properties of the original CSS file got lost, since the file essentially was re-defined from scratch.

This rendered the override/remove facility of the stylesheets[] property useless for most cases and theme authors had to resort to writing relatively complex PHP code to achieve the correct behavior. This problem has been fixed in Drupal 8 by introducing dedicated and separate theme .info.yml file properties for adding, overriding, and removing stylesheets.

Drupal 7

mytheme.info:

; Add a new CSS file:
stylesheets[all][] = layout.css

; Override a CSS file:
; WARNING: The file is moved from its original position to the
;   end of the CSS files stack! Use the PHP override code below.
stylesheets[all][] = system.theme.css

; Remove a module CSS file by *adding* it but without supplying
; the actual file in the filesystem:
stylesheets[all][] = node.css

template.php:

/**
 * Implements hook_css_alter().
 */
function mytheme_css_alter(&$css) {
  // Use our vertical tabs style instead of the default one.
  if (isset($css['core/misc/vertical-tabs.css'])) {
    $css['core/misc/vertical-tabs.css']['data'] = drupal_get_path('theme', 'mytheme') . '/vertical-tabs.css';
  }
}

Drupal 8

mytheme.info.yml:

# Add a new CSS file:
stylesheets:
  all:
    - layout.css

# Override a CSS file:
stylesheets-override:
  - system.theme.css

# Remove a CSS file:
stylesheets-remove:
  - node.css

Notes

  • All CSS files are "keyed" by their file (base)names, which means that you are free to put your theme's CSS files into a ./css subdirectory and the override/remove properties still work as you'd expect; i.e., they do not care for the path/directory names and this works, too:
    # Override the system.theme.css file with our version in the ./css subdirectory:
    stylesheets-override:
      - css/system.theme.css
    

Inheritance

The override and remove logic applies to base themes, too. The behavior and logic is how you would expect it to be — the following table describes the effects:

Description Base theme Sub theme File used
Override combinations:
Base theme overrides a stylesheet, sub theme inherits it.
stylesheets-override:
  - file.css
        
base-theme/file.css
Sub theme overrides a stylesheet.
stylesheets-override:
  - file.css
        
sub-theme/file.css
Base theme adds a stylesheet, sub theme overrides it.
stylesheets:
  all:
    - file.css
        
stylesheets-override:
  - file.css
        
sub-theme/file.css
Base theme removes a stylesheet, sub theme overrides it. stylesheets-remove[] = file.css
stylesheets-remove:
  - file.css
        
stylesheets-override:
  - file.css
        
sub-theme/file.css
Remove combinations:
Base theme removes a stylesheet; sub theme inherits it.
stylesheets-remove:
  - file.css
        
None
Sub theme removes a stylesheet.
stylesheets-remove:
  -file.css
        
None
Base theme adds a stylesheet; sub theme removes it.
stylesheets:
  all:
    - file.css
        
stylesheets-remove:
  - file.css
        
None
Base theme overrides a stylesheet, sub theme removes it.
stylesheets-override:
  - file.css
        
stylesheets-remove:
  - file.css
        
None
Impacts: 
Themers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done

Comments

SebCorbin’s picture

I'm confused, is this compatible with http://drupal.org/node/1876152 ?

nbz’s picture

From what I understand, that is for modules, this is for themes.

Module .info files no longer handle theme related stuff.
Theme .info files can override currently attached css files.

bskibinski’s picture

In the note you state that files are keyed by the basename, and the path shouldn't matter, and you can use css/system.theme.css or just system.theme.css.

I'm working on a theme for Drupal 8, and at the moment you still need to define the correct path to your overide.css.
I'm not sure if this is a bug in Drupal 8 at the moment, or that this feature has changed over time.

I tried overiding normalize.css in a multi-site, theme, but i needed to define the path in the .info.yml file ('styles/normalize.css').

(Or, hopefully, i'm just doing something horribly wrong;)

anneeasterling’s picture

Per change here, stylesheets-override is now gone:
https://www.drupal.org/node/2473199

Adding comment here so no one else with waste an hour trying to debug stylesheets-override.

brianmercer’s picture

Using Drupal 8.0.4 and enjoying the new theme stuff. However...

stylesheets-remove didn't work for me with just the file name. I couldn't find any current documentation on the web, but the test themes that come with core gave me the format needed.

I have a custom theme with no base theme stated. That causes the "Stable" hidden theme to act as a base theme. To remove a stylesheet from my new theme I had to do:


stylesheets-remove:
- '@stable/css/core/vertical-tabs.css'

see https://www.drupal.org/node/2473869

davidhernandez’s picture

These are essentially deprecated. You'll want to use libraries-extend and libraries-override for everything from now on.

https://www.drupal.org/theme-guide/8/assets#override-extend

brianmercer’s picture

Gotcha

  core/drupal.vertical-tabs:
    css:
      component:
        /core/themes/stable/css/core/vertical-tabs.css: /themes/custom/my_theme/css/core/vertical-tabs.css

I don't know why the leading slash is necessary, but it is.

Wim Leers’s picture

Because you're going outside of the current extension. You only need the leading slash for /core/themes/stable/css/core/vertical-tabs.css, you should be able to simplify /themes/custom/my_theme/css/core/vertical-tabs.css to just css/core/vertical-tabs.css, because that lives inside the current theme.