Welcome to your SplitCSS Documentation! Here you can find out how to use the SplitCSS API to reduce the amount of unused CSS on your pages.
In order to use the SplitCSS API, you will need to register and create a new API Key.
Once you have your API Key, you can use it to make calls to the SplitCSS API.
You can use your API Key in the URL, as a query string parameter, or as an Authorization Bearer request header.
If you pass your API Key as a query string parameter, your URL will look like this:
https://api.splitcss.com/clean-css?token=YOUR_API_KEY
If you pass your API Key as a request header, the "Authorization" header should look like this:
Authorization: Bearer YOUR_API_KEY
The SplitCSS API accepts JSON and can return either JSON or CSS.
The API currently offers two endpoints: /clean-css and /critical-css
Description: reduces the amount of loaded CSS on the specific HTML page by returning only the styles for the selectors within the HTML document.
Returns: JSON or CSS with all the styles about the elements encountered in the provided HTML document.
Endpoint Infos:
A URL to a HTML page and a list of URLs to CSS files.
| Param | Description | Type |
|---|---|---|
html_url |
The HTML page to be optimized | required |
css_urls[] |
The CSS URLs to be searched | required |
output |
css (default) or json | optional |
bypass_cache |
refresh cache for this HTML URL | optional |
So, let's assume that we would like to reduce the unused CSS on the following HTML page:
https://example.com/favorite-page.html
It contains the following HTML:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Favorite Page</title>
<link rel="stylesheet" href="/style.css">
</head>
<body>
<h1 class="title">Favorite Page</h1>
<p class="description">This is my favorite page.</p>
</body>
</html>
The CSS, can be found on the following URL:
https://example.com/style.css
It contains the following CSS:
.title {
font-size: 24px;
color: #000;
}
.description {
font-size: 16px;
color: #444;
padding: 2px;
}
.infobox {
background: #dadada;
padding: 5px;
}
As you can see, the class infobox is not used anywhere in favorite-page.html.
Maybe it's used somewhere else on the website, like on services.html, but every time we load favorite-page.html, that class is travelling to the browser for nothing.
Sidenote: yes, most browsers will cache the CSS once it's downloaded, but we shouldn't make them store CSS that is not anywhere on the page anyway.
Now, let's call the API. We will first choose the output to be JSON.
Our request to the API would look like this:
curl -X GET \
'https://api.splitcss.com/clean-css?html_url=https://example.com&css_urls[]=https://example.com/style.css&output=json'
\
-H 'Authorization: Bearer YOUR_API_KEY'
Since we chose JSON output, our response will look like this:
{
"css": ".title{font-size: 24px;color: #000;}.description{font-size: 16px;color: #444;padding: 2px;}"
}
If we choose a CSS response, we will get the following response:
.title {
font-size: 24px;
color: #000;
}
.description {
font-size: 16px;
color: #444;
padding: 2px;
}
So now, as you can see the class .infobox is not included in the response.
You can repeat the process for different individual URLs on your website.
Now, let's see how we can consume the API in our application. Let's assume that our application is written in PHP and that we have the following URL:
https://example.com/favorite-page.php
It looks like this:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Favorite Page</title>
<link rel="stylesheet" href="/styles.php?html_url=https://example.com/favorite-page.php&css_urls[]=https://example.com/style.css">
</head>
<body>
<h1 class="title">Favorite Page</h1>
<p class="description">This is my favorite page.</p>
</body>
</html>
We notice that there is a call to a script called styles.php, which looks like this:
<?php
$apiToken = 'MY_API_TOKEN'; // replace with your real one
$htmlUrl = urldecode( $_GET['html_url'] );
$cssUrls = urldecode( $_GET['css_urls'] );
$output = 'css';
$splitCssUrl = "https://api.splitcss.com/clean-css?html_url={$htmlUrl}&css_urls[]={$cssUrls}&output={$output}&token={$apiToken}";
echo file_get_contents( $splitCssUrl );
Now the browser will use the necessary CSS from SplitCSS and cache it as usual. The difference is, this CSS file will be smaller in size, since there will be less unused CSS classes present in it.
Keep in mind that you will need to pass absolute URLs and they have to be urlencoded.
Of course, you can write more sophisticated ways of using the API, like implementing a caching mechanism for requests to the SplitCSS API.
If you happen to have a Laravel application, you might want to check out our package on Github.
Description: Generates the critical CSS (above the fold) for the given URL.
Returns: JSON or CSS with the above-the-fold styles for the provided HTML document.
Endpoint Infos:
| Param | Description | Type |
|---|---|---|
html_url |
The HTML page to be optimized | required |
css_urls[] |
The CSS URLs to be searched | required |
width |
above-the-fold width (default: 1300) | optional |
height |
above-the-fold height (height: 900) | optional |
output |
css (default) or json | optional |
bypass_cache |
refresh cache for this HTML URL | optional |
curl --request GET \
--url 'https://api.splitcss.com/critical-css?html_url=https://example.com&css_urls[]=https://example.com/style.css' \
--header 'authorization: Bearer YOUR_API_KEY'
Let's assume again that our stylesheet can be found on the following URL:
https://example.com/style.css
It contains the following styles:
.title {
font-size: 24px;
color: #000;
}
.description {
margin-top: 900px; /* To demonstrate content below the fold */
font-size: 16px;
color: #444;
padding: 2px;
}
If our HTML document (in this example generated by PHP), favorite-page.php, looks like this:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Favorite Page</title>
<style>
<?php include_once('critical-css.php'); ?>
<style>
<link rel="stylesheet" href="/styles.php?html_url=https://example.com/favorite-page.php&css_urls[]=https://example.com/style.css">
</head>
<body>
<h1 class="title">Favorite Page</h1>
<p class="description">This is my favorite page.</p>
</body>
</html>
Then, our critical-css.php script can look like this:
<?php
$apiToken = 'MY_API_TOKEN'; // replace with your real one
$htmlUrl = urldecode( $_GET['html_url'] );
$cssUrls = urldecode( $_GET['css_urls'] );
$output = 'css';
$splitCssUrl = "https://api.splitcss.com/critical-css?html_url={$htmlUrl}&css_urls[]={$cssUrls}&output={$output}&token={$apiToken}";
echo file_get_contents( $splitCssUrl );
Now, the HTML output of our script favorite-page.php will be:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Favorite Page</title>
<style>
.title {
font-size: 24px;
color: #000;
}
<style>
<link rel="stylesheet" href="/styles.php?html_url=https://example.com/favorite-page.php&css_urls[]=https://example.com/style.css">
</head>
<body>
<h1 class="title">Favorite Page</h1>
<p class="description">This is my favorite page.</p>
</body>
</html>
Lastly, we can make the non-critical CSS load asynchronously:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Favorite Page</title>
<style>
<?php include_once('critical-css.php'); ?>
<style>
<link rel="stylesheet" media="print" onload="this.media='all'" href="/styles.php?html_url=https://example.com/favorite-page.php&css_urls[]=https://example.com/style.css" >
</head>
<body>
<h1 class="title">Favorite Page</h1>
<p class="description">This is my favorite page.</p>
</body>
</html>
By doing this, our CSS will no longer be a blocking request and the page will load faster.
Description: clears the cache for all URLs processed with the provided API key.
Returns: JSON with details about the outcome.
Endpoint infos:
This endpoint accepts no additional parameters.
This is how you can make a request to the endpoint:
curl --location --request GET 'https://api.splitcss.com/invalidate-all' \
--header 'Authorization: Bearer YOUR_API_KEY'
Let's say we have a stylesheet and we want to make a change to it:
https://example.com/style.css
Normally, once you made the change, you would add some kind of change to the URL of the stylesheet to force browsers to apply the new stylesheet, like this:
https://example.com/style.css?v=1.01
With SplitCSS, you can still do this and it will work fine. Just pass that URL to the /clean-css endpoint and it will return you the updated stylesheet.
But if you don't use this technique and you would like to push the changes of your stylesheets immediately to all users, you can use the /invalidate-all endpoint.
As an alternative, you can pass the bypass_cache=1 parameter or go to your profile and clear the cache.
What if we change something in the HTML document?
In this case, if you added new HTML elements that should by styled with new CSS classes, you have a number of options:
https://example.com/favorite-page.php?v=1.01 in the call of the /clean-css endpoint.You might find it helpful to check out the complete list of frequently asked questions or contact us for more information.