A back to the basics CSS starter kit. For when you don’t need the whole boot.
Shoelace is a starter kit, not a framework. Think of it as a CSS reset sprinkled with helpful components. Bootstrap users will find it familiar, yet refreshing.
Shoelace is highly customizable through CSS variables. It doesn’t require Less, Sass, or any preprocessing at all. The minified version is only 31KB.
Just link to the stylesheet, add your customizations, and start building stuff.
<link rel="stylesheet" href="dist/shoelace.min.css">
The purpose of this project is to provide a modern, lightweight, customizable, and extensible boilerplate for building websites and web applications.
Shoelace was created by @claviska for Surreal CMS. It is available under the MIT license. Love it? Consider making a small donation. 🙌
You can customize Shoelace without editing core files. This makes it easier to update later
on. To add customizations, simply override one or more of the CSS variables found in
variables.css in your own stylesheet.
For example, you can customize the default text color and background like this:
:root {
--body-color: white;
--body-bg-color: black;
}
Refer to variables.css for a complete list of variables in Shoelace.
You can use any of Shoelace’s variables in your own stylesheet. This makes it easy to reuse colors, paddings, etc. without hardcoding them, and provides a foundation for building your own components to extend Shoelace.
.your-selector {
color: var(--state-danger);
}
Shoelace gives you an easy way to customize most HTML elements with variables. You don’t need to apply any classes to achieve these styles — just use the appropriate elements.
For easier spacing, Shoelace removes top margins and applies a bottom margin to block
elements. By default, text sizing and spacing is measured in rem and
em units.
<h1> – <h6><p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quaerat excepturi repellendus nostrum dolorum dignissimos quis non, minus debitis laborum vero cupiditate sequi neque, magnam dolore nemo possimus, soluta ducimus eaque.
Blanditiis ea qui, veritatis animi recusandae praesentium magnam. Commodi placeat, laboriosam accusamus laudantium quasi eveniet soluta illo ducimus quis doloremque mollitia, officia pariatur deleniti reprehenderit, maxime, dicta libero vero cum.
<ol><ul><dl><blockquote>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Mollitia ipsam enim reprehenderit placeat ab voluptate totam suscipit voluptas, culpa pariatur eos quas, sequi unde perferendis officiis! Officiis eligendi eaque facilis.
<pre>CLS SCREEN 13 PRINT "SHOELACE IS AWESOME"
| Element | Example |
|---|---|
<strong> |
This is strong text |
<em> |
This is emphasized text |
<u> |
This is underlined text |
<s> |
|
<a> |
This is link text |
<small> |
This is small text |
<big> |
This is big text |
<sup> |
This is superscript text |
<sub> |
This is subscript text |
<code> |
This is code text |
<samp> |
This is samp text |
<var> |
This is var text |
<kbd> |
This is kbd text |
<abbr> |
This is abbr text |
<del> |
|
<ins> |
This is ins text |
<mark> |
This is mark text |
Create an alert by applying the alert alert-[modifier] class to an element such
as a div.
<div class="alert">Default</div> <div class="alert alert-success">Success</div> <div class="alert alert-info">Info</span> <div class="alert alert-warning">Warning</div> <div class="alert alert-danger">Danger</div> <div class="alert alert-inverse">Inverse</div>
Create a badge by applying the badge badge-[state] class to an element such as a
<span>. Badges are sized relative to their parent element.
<span class="badge">Default</span> <span class="badge badge-success">Success</span> <span class="badge badge-info">Info</span> <span class="badge badge-warning">Warning</span> <span class="badge badge-danger">Danger</span> <span class="badge badge-inverse">Inverse</span>
Default Success Info Warning Danger Inverse
To create a button, use the <button> element or apply the
button class to another element such as an <a>. You can change
a button’s appearance using the button-[state] modifier.
<button type="button">Default</button> <button type="button" class="button-success">Success</button> <button type="button" class="button-info">Info</button> <button type="button" class="button-warning">Warning</button> <button type="button" class="button-danger">Danger</button> <button type="button" class="button-inverse">Inverse</button> <button type="button" class="button button-link">Link</button>
Use the button-small and button-big modifiers to change the size of
a button.
Use the button-block modifier to make the button span the entire width of its
parent element. You can also mix and match modifiers as needed.
Disabled buttons look like this. Set the disabled property on
<button> elements to achieve this effect. For all other elements, apply
class="disabled" instead.
You can force buttons to have an active state by applying the active class.
File inputs are notoriously hard to style properly in every browser. Shoelace offers file buttons as an alternative. These are much easier to style consistently, but come with the caveat that the name (or number) of files selected will not be automatically shown to the user. This aspect of a file button’s UX can be handled effectively with JavaScript, but this is left as an excercise for the user.
File buttons are simply label elements with the button class and a
nested file input.
<label class="button"><input type="file"></label>
Shoelace gives you beautiful forms without hassle. Most form controls don’t need a special class for styling.
Form controls are styled at 100% of the width of their parent element.
| Input Type | Example |
|---|---|
checkbox |
|
date |
|
email |
|
file
File inputs aren’t supported. Use a file button instead. |
|
number |
|
password |
|
radio |
|
range |
|
search |
|
select |
|
text |
|
textarea |
|
time |
You can change the size of most form controls with the input-small and
input-big modifiers.
<input type="text" class="input-small" placeholder="Small"> <input type="text" placeholder="Default"> <input type="text" class="input-big" placeholder="Big"> <select class="input-small"><option>Item</option></select> <select><option>Item</option></select> <select class="input-big"><option>Item</option></select>
Disabled form controls look like this:
Read-only form controls look like this:
Related form controls can be grouped in a <fieldset>. An optional
legend can be used to display a name for the group.
<fieldset> <legend>User</legend> ... </fieldset>
For proper spacing of individual form controls and labels, wrap them in
input-block elements.
<div class="input-block"> <label>Name</label> <input type="text"> </div> <div class="input-block"> <label>Email</label> <input type="email"> </div> <div class="input-block"> <label><input type="checkbox"> Remember me</label> </div>
Form controls and buttons can be grouped by wrapping them in input-group
containers.
<div class="input-group"> <input type="text"> <button type="button" class="button">Submit</button> </div> <div class="input-group"> <button type="button" class="button">Submit</button> <input type="text"> </div> <div class="input-group"> <input type="text" placeholder="First"> <input type="text" placeholder="Middle"> <input type="text" placeholder="Last"> <button type="button" class="button">Submit</button> </div> <div class="input-group"> <button type="button" class="button">Option 1</button> <button type="button" class="button">Option 2</button> <button type="button" class="button">Option 3</button> </div>
To create an input addon, use <span class="input-addon">. Addons
can appear anywhere inside an input group. Use the input-addon-[size]
modifier to change the size to match adjacent form controls.
<div class="input-group"> <span class="input-addon input-addon-small">$</span> <input type="text" class="input-small"> <span class="input-addon input-addon-small">.00</span> </div> <div class="input-group"> <span class="input-addon">$</span> <input type="text"> <span class="input-addon">.00</span> </div> <div class="input-group"> <span class="input-addon input-addon-big">$</span> <input type="text" class="input-big"> <span class="input-addon input-addon-big">.00</span> </div>
Form controls can be made valid or invalid using the input-valid and
input-invalid modifiers. It’s better to apply modifiers to the surrounding
input-block so labels will be styled as well, but modifiers can be applied
directly to form controls as needed.
<div class="input-block input-valid"> <label>Valid</label> <input type="text"> </div> <div class="input-block input-invalid"> <label>Invalid</label> <input type="text"> </div>
Create a pure CSS loader by applying the loader class to an empty
<span> element. You can use the loader-small and
loader-big modifiers to change the size.
<span class="loader loader-small"></span> <span class="loader"></span> <span class="loader loader-big"></span>
You can simulate a background loader using loader-bg. This is achieved using
position: relative on the container and the ::after pseudo-element.
You can use the loader-bg-small and loader-bg-big modifiers to
change the size.
<div class="loader-bg loader-bg-small"></div> <div class="loader-bg"></div> <div class="loader-bg loader-bg-big"></div>
Tab sets can be created using the markup below. By default, Shoelace renders tabs as pills because they look better than traditional tabs when rendered on smaller screens.
Note the class names used for the main container, the tab navs, and the tab panes. Also note
that each tabs links to its respective tab pane’s id.
To disable a tab, add disabled to the appropriate tab nav.
<div class="tabs">
<nav class="tabs-nav">
<a href="#tab-1" class="active">Tab 1</a>
<a href="#tab-2">Tab 2</a>
<a href="#tab-3">Tab 3</a>
<a href="#" class="disabled">Disabled</a>
</nav>
<div class="tabs-pane active" id="tab-1">
...
</div>
<div class="tabs-pane" id="tab-2">
...
</div>
<div class="tabs-pane" id="tab-3">
...
</div>
</div>
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Qui repellat ea magni magnam assumenda voluptas accusantium nemo. Iusto beatae illum mollitia aut quasi odit facilis officiis, laudantium debitis! Excepturi, quis!
Atque eius voluptatibus ipsa ex totam odit, quidem illo distinctio sit! Quod quae minus, aut itaque. Mollitia, dolore! Facere molestiae necessitatibus sint recusandae incidunt pariatur labore iste vel, velit odit.
Aperiam asperiores optio iusto qui nisi, perspiciatis, ipsum, tenetur explicabo earum et laboriosam odit magni maxime quos molestias aspernatur laudantium harum placeat tempora quae necessitatibus, aut dignissimos totam non! Quod.
Tabs are not interactive by default! Shoelace is a CSS starter kit, not a framework. For convenience, a lightweight sample script is provided to demonstrate how to make tabs interactive.
<script src="js/tabs.js"></script>
Tabs can be made vertical by adding custom CSS rules. Shoelace doesn’t include these styles by default because of the many ways tabs can be positioned, customized, and made responsive.
Here’s an example of vertical tabs that uses the CSS grid. The markup is exactly the same as the previous example, except the tabs container has a custom class and the following custom styles.
.tabs-vertical-example {
display: grid;
grid-template-columns: 25% 75%;
grid-gap: 2rem;
padding-right: 2rem;
}
.tabs-vertical-example .tabs-nav a {
display: block;
}
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Qui repellat ea magni magnam assumenda voluptas accusantium nemo. Iusto beatae illum mollitia aut quasi odit facilis officiis, laudantium debitis! Excepturi, quis!
Atque eius voluptatibus ipsa ex totam odit, quidem illo distinctio sit! Quod quae minus, aut itaque. Mollitia, dolore! Facere molestiae necessitatibus sint recusandae incidunt pariatur labore iste vel, velit odit.
Aperiam asperiores optio iusto qui nisi, perspiciatis, ipsum, tenetur explicabo earum et laboriosam odit magni maxime quos molestias aspernatur laudantium harum placeat tempora quae necessitatibus, aut dignissimos totam non! Quod.
By default, tables are plain and unstyled. To create a styled table, apply the
table class to a table element.
<table class="table">
<thead>
<tr><th>Item</th><th>Price</th></tr>
</thead>
<tbody>
<tr><td>Shoe Freshener</td><td>$4.79</td></tr>
<tr><td>Shoe Glue</td><td>$2.50</td></tr>
<tr><td>Shoe Polish</td><td>$5.25</td></tr>
<tr><td>Shoelaces</td><td>$3.99</td></tr>
</tbody>
</table>
| Item | Price |
|---|---|
| Shoe Freshener | $4.79 |
| Shoe Glue | $2.50 |
| Shoe Polish | $5.25 |
| Shoelaces | $3.99 |
Use the table-striped modifier to add stripes to alternating rows.
<table class="table table-striped"> ... </table>
| Item | Price |
|---|---|
| Shoe Freshener | $4.79 |
| Shoe Glue | $2.50 |
| Shoe Polish | $5.25 |
| Shoelaces | $3.99 |
Use the table-bordered modifier to add a border to the table.
<table class="table table-bordered"> ... </table>
| Item | Price |
|---|---|
| Shoe Freshener | $4.79 |
| Shoe Glue | $2.50 |
| Shoe Polish | $5.25 |
| Shoelaces | $3.99 |
Shoelace provides a number of helpful utility classes that make prototyping easier.
| Class | Example |
|---|---|
text-success |
This is success text |
text-info |
This is info text |
text-warning |
This is warning text |
text-danger |
This is danger text |
text-muted |
This is muted text |
text-small |
This is small text |
text-big |
This is big text |
text-bold |
This is bold text |
text-italic |
This is italic text |
text-left |
This is left-aligned text |
text-center |
This is centered text |
text-right |
This is right-aligned text |
text-justify |
This is justified text |
text-nowrap |
This is text that won’t wrap |
text-lowercase |
This is lowercase text |
text-uppercase |
This is uppercase text |
text-capitalize |
This is capitalized text |
Float utilities are provided to easily float elements to the left or right. Just apply the
float-left or float-right class to an element to float it
left or right.
A clearfix utility is also available to clear floated elements. Just apply the
clearfix class to the appropriate element.
Sizing utilities can be used to set a relative width or height on any element. Just apply
a width-[%] or height-[%] class and the appropriate element will be
sized accordingly. Sizes are available from 0 – 100 in multiples of five.
<div class="width-25">25%</div> <div class="width-50">50%</div> <div class="width-75">75%</div> <div class="width-100">100%</div> <div class="height-25">25%</div> <div class="height-50">50%</div> <div class="height-75">75%</div> <div class="height-100">100%</div>
Spacing utilties can be used to add or remove paddings and margins to any element. Just apply the desired class and the appropriate element will receive the respective padding/margin.
Class names are prefixed with m- or p- for margin and padding,
respectively. To apply a padding/margin to all sides of an element, use the following
classes:
p-[none|small|medium|big] m-[none|small|medium|big] Example: class="p-none m-big"
To apply a padding/margin to a specific side of an element, use one or more of the following classes:
p-[top|right|bottom|left|x|y]-[none|small|medium|big] m-[top|right|bottom|left|x|y]-[none|small|medium|big] Example: class="p-left-medium m-bottom-none"
You can also use m-x-auto to horizontally center a fixed width block.
Shoelace doesn’t ship with a grid system because you don’t need one. You should use the CSS Grid Layout instead.
If you have an obligation to support older browsers, consider using the Bootstrap grid without any extras.
Shoelace doesn’t bundle its own icons, but you can easily include your favorite library such as Font Awesome. They work superbly together.
This decision was intentional. It keeps Shoelace light and makes it more customizable.
TL;DR — you can use Shoelace as-is if you don’t care about Internet Explorer and older browsers (Edge is fine). If you need to support older browsers, just make sure to use a grid system and Myth as a polyfill.
Browser support for CSS variables is pretty good, but if you need to support Internet Explorer, consider using Myth as a polyfill. Myth lets you write standards-compliant CSS and “fixes” it for unsupportive browsers.
Browser support for the CSS Grid is very good, but if you need to support older browsers you can use a grid system instead.
Browser support for calc is
excellent. Shoelace uses this internally for
relative calculations. You can use it along with CSS variables too.
Browser support for color modifiers is non-existent. There is a draft, so hopefully that will change soon. Shoelace doesn’t use this feature, but it will when support improves.
Browser support for custom media queries is non-existent. There is a draft, so hopefully that will change soon. Shoelace doesn’t use this feature, but it will when support improves.