Create a theme

Extend UIkit and add your own unique theme.

How to start

By default, UIkit comes with a very basic theme. To modify the style, you don't have to edit any of the core framework files. Instead, you can extend UIkit by creating a custom theme. This allows you to easily update UIkit core files. We even provide some neat themes to get you started. To create your own theme, follow these steps:

1. Create the theme directory

Download or clone UIkit and install Node and Gulp. Finally create your theme folder here /custom/THEME-NAME. If the /custom directory is not present, create it first.

NOTE The /custom folder is set to git ignore, which prevents your custom files from being pushed into the UIkit repository. If you are working with a cloned version of UIkit's git repository, it is a good practice to have /custom as your own git repository. That way your theme files are under version control without interfering with the UIkit files.

2. Add your theme

Create the uikit.less file in the /custom/THEME-NAME folder and add the @import "../../src/less/uikit.less"; rule to access all Less files from the core framework and adopt its basic styling. That's it! You can start adding your own theme from scratch.

NOTE To get you started right away, we provide the default, gradient and almost-flat theme. All default files are already imported and you will also find all theme files with their related hooks. So all you need to do is to duplicate and rename the folder into the /custom directory.

3. Customizer and Tests

Run the gulp task indexthemes in your UIkit folder. Now the newly created themes will be available automatically in the Customizer and test files.

4. Build your theme

You can generate your theme's CSS from within the Customizer. If you want to use a gulp task instead, run gulp dist -t THEME-NAME. The generated files will be located in the dist/ folder.

Best theming practices

There are different approaches to style your theme. We recommend the following workflow.

1. Use variables

The first thing to do is to customize the values of already declared variables. You can find all variables for each component inside their Less files of the core framework and override them in your theme.

Example

// default value
@button-height: 30px;

// new value
@button-height: 35px;

2. Use hooks

To prevent overhead selectors, we use Mixins from Less, which hook into predefined selectors from the UIkit source and apply additional properties. Selectors don't have to be repeated throughout all documents and gobal changes can be made much more easily.

Example

// CSS rule
.uk-panel {
    background: @background;

    // mixin to add new declaration
    .hook-panel;
}

// mixin to add new declaration
.hook-panel() { color: #fff; }

3. Miscellaneous hooks

Should there be neither a variable nor a hook available, you can of course create your own selector. To do so, use the .hook-panel-misc hook and write your selector inside. This will sort your new selector to the right place of the compiled CSS file.

Example

// misc mixin
.hook-panel-misc() {

    // new rule
    .uk-panel a { color: #f00; }
}