1. Include a <link> to cleanslate.css in the host page
2. Add the class cleanslate to the HTML container element of the widget
3. Add !important to all of the widget’s CSS rules
4. (optional) Set the default styles on the widget container

For more details, see the ‘Usage’ section.

<section class="mywidget cleanslate">
    This is a widget. Styles are reset
    with Cleanslate, then modified.
</section>

<style>
    .mywidget {
        color: white !important;
        background-color: darkblue !important;
        padding: 2em !important;
    }
</style>

Cleanslate is useful when there are existing CSS styles on a page, and you want to prevent those styles cascading into some part of the page. This is not a stylesheet to use when developing your own website (for that, try Eric Meyer’s classic “Reset CSS” or the “HTML5 Doctors’ adaptation”.

The stylesheet can be useful when distributing content (e.g. a widget, or syndicated news) to third-party websites. The CSS rules in the host site may be unknown and unpredictable, or may change in future without notice, or there may be so many websites you need to distribute to that it is impractical to write specific CSS that overrides the styles in each one. In such situations, the Cleanslate stylesheet will aggressively reset your portion of the content (and nothing else) back to some reasonable default values that you can then build from.

Third-party content is often distributed in iframes. Because JavaScript within an iframe can be prevented from accessing the host page, iframes are particularly useful when the host site has security concerns and does not explicitly trust the third-party content.

However, iframes have some drawbacks: * You cannot display content outside of the box of the iframe * It is tricky to resize the iframe to match the size of its contents * Your content will be unable to interact with the host page, even if it is trusted * Search engines like Google will not see the content on the host page. Content that is syndicated from a partner website can avoid this by being directly included in the host page.

Iframe-based resetting for distributed content

Cleanslate only resets CSS styles. But if you also need to protect your content from JavaScript on the host page, then see “AppleOfMyIframe”’, which allows you to inject HTML into a “sourceless” iframe element that the browser treats as being on the same domain as the host.

If your host page needs to isolate and sandbox third-party JavaScript, then you might want to use “Sandie”.

The stylesheet lists all possible HTML elements, and assigns them the default (or otherwise appropriate) values for every CSS property. It only looks within elements that have a class attribute of "cleanslate".

This approach, of aggressively resetting the styles on a host page with the use of !important rules, came about while developing the BBC World Service widget, where the widget was injected into a page, not with an iframe, but a simple <div> element (the widget’s “lightbox” overlay is similarly just a simple <div>). The !important styles helped us to prevent any unpredictable CSS “bleeding” into the widget.

The following documents were invaluable as building blocks for Cleanslate:

• Eric Meyer’s Reset CSS
• HTML5 Reset Stylesheet by Richard Clark
• Default stylesheet for HTML 4
• Default stylesheet for Mozilla Firefox
• W3C CSS2 Cascade & Inheritance
• W3C CSS3 Selectors
• List of CSS Properties
• CSS 2.1 User Agent Style Sheet Defaults
• Internet Explorer User Agent Style Sheets