SharePoint CSSLink

Understanding SharePoint:CSSLink and how to add your custom CSS in SharePoint 2010

CSS is a wonderful tool for branding SharePoint; unfortunately SharePoint 2010 has done a decent job of making things pretty hairy and confusing with working with CSS in a SharePoint site. Something we get asked all the time in our classes is “where do I link to my custom CSS file?” Great question and the answer isn’t just “from your master page”.

Please note this article is cross posted on nothingbutsharepoint.com.

Key to remember: CSS builds upon itself

One of the most important features of CSS is that CSS style statements build on each other. For example:

p {color: green;}

p {font-weight: bold;}

Our resulting paragraph style would be green AND bold. The inclusion of the second style statement does not wipe out the presence of the first. There is a lot of building on style statements in SharePoint.

Second key to remember: CSS loves order

Looking at our example from above, what happens if the style statements listed this instead:

p {color: green;}

p {color: red;}

Well now we have a conflict. The paragraph text would end up being red since that property was listed last. There is a whole slew of things that can go into determining what is applied, but a general rule of thumb is last thing specified is the last thing applied.

So let’s take this same example, and put the style statements in separate files.

SharePoint CSS file:

p {color: green;}

Your custom CSS file:

p {color: red;}

If you want the paragraph text to be red, then you want to make sure your CSS file is referenced after the SharePoint CSS file.

SharePoint CSS

There are quite a few CSS files installed by SharePoint 2010. Like, a lot. We won’t cause your eyes to bulge today by rattling off numbers, but know that SharePoint 2010 actually uses around 50 CSS files. However, not every CSS file is sent to the web browser for every web page. Instead SharePoint only sends the CSS files that are needed for the given web page.

Within these files is many lines of CSS. The worst offender is corev4.css clocking in at over 7400 lines of code. What you don’t want to do is mix in your CSS changes into these files. Maintenance nightmare city! Instead you need to create a separate CSS file for just your custom style statements and changes.

Insert SharePoint:CssLink control

If you take a stroll around a SharePoint master page you will find the following control within the HEAD element in the HTML:

<SharePoint:CssLink runat="server" Version="4"/>

This little guy has a big job. It will sort out which CSS files are needed for the given SharePoint web page and send them along to the browser. For example, the home page for an Enterprise Wiki SharePoint site only loads the following CSS files, in this order:

  • calendarv4.css
  • controls.css
  • layouts.css
  • page-layouts-21.css
  • search.css
  • corev4.css

A team site on the other hand will load these CSS files, in this order:

  • search.css
  • wiki.css
  • corev4.css

And a list view page will load these files, in this order:

  • search.css
  • corev4.css

You will not see more traditional LINK tags pointing to SharePoint CSS files. The SharePoint:CssLink control handles it all.

SharePoint:CssLink control does one more thing

If you are working with publishing sites, you can go into the Master Page settings under Site Settings and point to a CSS file using the Alternate CSS URL setting. The SharePoint:CssLink control will look to see if a file has been set here, and will push that CSS file reference to every web page. It will push it as the last file. For example, looking back at the list view CSS files from above, if an Alternate CSS URL was specified for the site, the list of loaded CSS files would be, and in this order:

  • search.css
  • corev4.css
  • alternate.css (Alternate CSS URL)

Looping back to CSS likes order

To review…

  • You will use CSS extensively to brand SharePoint.
  • SharePoint has a lot of CSS files.
  • Due to the size of SharePoint CSS, we don’t want to mix in our own CSS style statements so instead we will use a custom CSS file.
  • SharePoint uses one control, SharePoint:CssLink, to figure out what CSS files to load on the web page, including the file set for Alternate CSS URL.
  • In regards to the files that SharePoint:CssLink pushes to the browser, the CSS file from Alternate CSS URL (if any) is pushed last.
  • CSS likes order when it comes to applying conflicting style properties. In general, last thing specified is the last thing applied.

Bottom line – You have two choices for including your custom CSS:

  1. Specify your custom CSS file for the Alternate CSS URL in Site Settings.
  2. Reference your custom CSS in the HEAD of the master page file, AFTER the SharePoint:CssLink control.
    <!-- =SharePoint - CSS -->
        <SharePoint:CssLink runat="server" Version="4"/>
    <!-- =Custom - CSS -->
        <link rel="stylesheet" type="text/css" href="/Style Library/INSERT_PATH.css" />

The one exception

Hey, there is always at least one exception! If you are using a reset CSS file for your SharePoint site, you will need to link to that file BEFORE the SharePoint:CssLink control. We don’t recommend linking to it from the Alternate CSS URL setting.

<!-- =Custom =Styles - Browser reset - optional -->
 <link rel="stylesheet" type="text/css" href="/Style Library/INSERT_PATH.css" />
<!-- =SharePoint - CSS -->
 <SharePoint:CssLink runat="server" Version="4"/>
<!-- =Custom - CSS -->
 <link rel="stylesheet" type="text/css" href="/Style Library/INSERT_PATH.css" />

This was originally posted on NothingButBranding.com in October 2012, which is a site that has since been closed.