Shoelace.css 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 and much smaller when gzipped.

Just link to shoelace.css and add customizations to your stylesheet.

<link rel="stylesheet" href="shoelace.css">

<style>
  :root {
    --body-color: white;
    --body-bg-color: black;
    --color-primary: #09d;
  }
</style>

Shoelace was created by @claviska for Surreal CMS. It’s available under the MIT license.

Fork Download Report a Bug Star Follow Donate

Version 1.0.0-beta4

# Documentation

• Installing
• Customizing
• Content
• Alerts
• Badges
• Buttons
• Forms
• Loaders
• Tabs
• Tables
• Utilities
• Grid System
• Icons
• Browser Support
• Attribution

# Installing

Shoelace is incredibly easy to use. To get started, simply link to shoelace.css in your project. You can use the CDN version or download the source manually.

CDN

The easiest way to use Shoelace is via CDN. This service is generously provided by the folks at KeyCDN.

<link rel="stylesheet" href="https://cdn.shoelace.style/1.0.0-beta4/shoelace.css">

Download

Alternatively, you can download the source and link to shoelace.css from your own server.

<link rel="stylesheet" href="dist/shoelace.css">

NPM

If you’re using NPM, you can install Shoelace by running:

npm install --save-dev shoelace-css

# Customizing

You can customize Shoelace without editing core files or using a preprocessor. To add customizations, simply override one or more of the 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;
}

Using Variables

You can use any of Shoelace’s variables in your stylesheet. This makes it easy to reuse values without hardcoding them. It also provides a foundation for extending Shoelace with your own custom components.

.your-selector {
  color: var(--state-danger);
}

Refer to variables.css for a complete list of variables in Shoelace. If you’re not familiar with CSS variables, this article will bring you up to speed. There’s also an interactive demo if you want to try it out.

Custom Components

You can create custom components to extend Shoelace’s functionality. Here are some best practices to keep things consistent and easy for others to understand.

Familiarize yourself with Shoelace’s naming conventions. A custom accordion component, for example, would have a class name such as accordion, modifier classes such as accordion-open, and variable names that look like --accordion-bg-color. Try to follow similar patterns as much as possible.

Define new variables when it makes sense to. Take a look at variables.css to see how existing components are defined. Many use core variables instead of hardcoded properties as default values. This makes it easy for users to customize things quickly, but still provides enough flexibility to style individual components.

Semantic markup is strongly encouraged. Custom components should use the most appropriate elements and the minimal amount of markup required.

Keep everything together. During development, each component should be in its own folder along with its stylesheets, scripts, and documentation. Components shouldn’t depend on other components’ styles or scripts. This makes it easier to add or remove components from your app without affecting others. Of course, it’s perfectly fine to bundle components for optimization purposes in production.

# Content

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 tags.

For easy spacing, Shoelace removes top margins and applies a bottom margin to block elements. By default, text sizing and spacing is measured in rem units.

Headings <h1> – <h6>

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Paragraphs <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.

Ordered Lists <ol>

1. List item 1
2. List item 2
   1. Nested item 1
   2. Nested item 2
   3. Nested item 3
3. List item 3

Unordered Lists <ul>

• List item 1
• List item 2
  • Nested item 1
  • Nested item 2
  • Nested item 3
• List item 3

Definition Lists <dl>

Term 1

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Earum autem perferendis exercitationem asperiores fuga incidunt, nam dicta amet. Dolor eligendi nisi praesentium placeat officiis esse corporis molestiae. Doloremque accusamus, vel!

Term 2

Veritatis repellendus porro ipsam beatae temporibus natus id adipisci nobis accusantium quidem eum fugit cupiditate deleniti nisi nesciunt dicta officia, enim, atque corporis neque error. Unde saepe molestiae hic voluptatibus?

Blockquotes <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.

Preformatted Text <pre>

CLS
SCREEN 13
PRINT "SHOELACE IS AWESOME"

Text Formats

# Alerts

Create an alert by applying the alert class to an element such as a <div>. You can change an alert’s appearance using the alert-* modifier.

<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>

# Badges

Create a badge by applying the badge class to an element such as a <span>. You can change a badge’s appearance using the badge-* modifier.

<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

Badges are sized relative to their parent element.

<h1>Heading 1 <span class="badge">Badge</span></h1>
<h2>Heading 2 <span class="badge">Badge</span></h2>
<h3>Heading 3 <span class="badge">Badge</span></h3>
<p>Paragraph <span class="badge">Badge</span></p>

Heading 1 Badge

Heading 2 Badge

Heading 3 Badge

Paragraph Badge

# Buttons

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-* 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>

Default Success Info Warning Danger Inverse Link

Use the button-small and button-big modifiers to change the size of a button.

Small Button Normal Button Big 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.

Small Block Button Normal Block Button Big Block Button

Disabled buttons look like this. Set the disabled property on <button> elements to achieve this effect. For all other elements, apply class="disabled" instead.

Default Success Info Warning Danger Inverse

You can force buttons to have an active state by applying the active class.

Default Success Info Warning Danger Inverse

File Buttons

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>

Select File

# Forms

Shoelace gives you beautiful forms without hassle. Most form controls don’t need a special class for styling.

Form Controls

Form controls are styled at 100% of the width of their parent element.

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:

Form Control Spacing

For proper spacing of individual form controls, wrap them in input-single containers.

<div class="input-single">
  <label>Name</label>
  <input type="text">
</div>

<div class="input-single">
  <label>Password</label>
  <input type="password">
</div>

<div class="input-single">
  <label><input type="checkbox"> Remember me</label>
</div>

Input Groups

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>

Input Addons

To create an input addon, use <span class="input-addon">. Addons can appear anywhere inside an input group. Use the input-addon-* 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 Groups

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>

Validation

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-single so labels will be styled as well, but modifiers can be applied directly to form controls as needed.

<div class="input-single input-valid">
  <label>Valid</label>
  <input type="text">
</div>

<div class="input-single input-invalid">
  <label>Invalid</label>
  <input type="text">
</div>

# Loaders

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>

# Tabs

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 tab 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>

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>

Vertical Tabs

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: 30% 70%;
}

.tabs-vertical-example .tabs-nav {
  padding-right: 2rem;
}

.tabs-vertical-example .tabs-nav a {
  display: block;
}

# Tables

Tables are styled for you automatically.

<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>

Striped Tables

Use the table-striped modifier to add stripes to alternating rows.

<table class="table-striped">
  ...
</table>

Bordered Tables

Use the table-bordered modifier to add a border to the table.

<table class="table-bordered">
  ...
</table>

# Utilities

Shoelace provides a number of helpful utility classes that make prototyping easier.

Text Utilities

Float Utilities

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

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 as percentages 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 Utilities

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.

# Grid System

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.

# Icons

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.

# Browser Support

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.

# Attribution

Special thanks to the following individuals and organizations for their contributions to Shoelace.css. Listed in no particular order.

• Cory LaViska – for creating this project
• Adam K Olson – for designing an awesome logo
• Bootstrap – for inspiration
• KeyCDN – for providing a CDN
• GitHub – for hosting this and many other open source repos
• Surreal CMS – for sponsoring this project