topic Creating a UIkit sub-theme

Create a custom theme by inheriting the UIkit 8 base theme.

Creating a custom theme utilizing UIkit is just like creating any other theme. The only difference with creating a UIkit sub-theme is your custom theme will automatically inherit all UIkit offers without having to reinvent the wheel.

Creating a sub-theme manually

UIkit for Drupal ships with a STARTERKIT to get you going quickly when creating a UIkit sub-theme. If you're comfortable using the command line, we recommend Creating a sub-theme using Drush instead.

To get started you can copy the STARTERKIT folder in the root directory of UIkit and paste it where you place your themes in your Drupal installation. See Drupal 8 Theme folder structure to learn where to place your themes in Drupal 8.

The folder structure of the STARTERKIT looks like:

|-config
|  |-install
|     |-STARTERKIT.settings.yml
|  |-optional
|     |-block.block.STARTERKIT_*.yml
|  |-schema
|     |-STARTERKIT.schema.yml
|
|-css
|  |-STARTERKIT.base.css
|  |-STARTERKIT.component.css
|  |-STARTERKIT.layout.css
|  |-STARTERKIT.theme.css
|
|-includes
|  |-alter.inc
|  |-preprocess.inc
|  |-process.inc
|  |-theme.inc
|
|-js
|  |-STARTERKIT.theme.js
|
|-favicon.ico
|-logo.png
|-logo.svg
|-README.txt
|-screenshot.png
|-STARTERKIT.info.ymltmp
|-STARTERKIT.libraries.yml
|-STARTERKIT.theme
|-theme-settings.php

Next you will need to replace all instances of STARTERKIT in the file names and contents with your theme name. Remember to use the machine name for file names and functions, i.e. "theme_name" and a human-readable name elsewhere, i.e. "Theme name".

Finally, one last change is needed in order for Drupal to recognize your new sub-theme. Remove the .ymltmp extension from the theme info file, i.e. theme_name.info.yml. We included the .ymltmp extension in STARTERKIT so Drupal would not display STARTERKIT on the Appearance page.

That's it! You are now ready to start making changes to your new sub-theme. More information on customizing UIkit themes can be found in the UIkit theme settings topic.

Creating a sub-theme using Drush

UIkit for Drupal comes equipped with an easy-to-use Drush command to create a sub-theme from the command line. This provides rapid development of your UIkit sub-theme, creating the files necessary for you with one simple command.

The Drush command uikit-starterkit (alias uikit-sk) uses the STARTERKIT now included with the project.

Use example

drush uikit-sk machine_name "Theme name" --path=sites/default/themes --description="Awesome theme description." 

[machine_name], [--path] and [--description] are all optional; only the theme name (wrapped in double-quotes) is required. Use "drush uikit-sk --help" to view more detailed help information. If Drush reports it cannot find the command, be sure to run "drush cc drush" to clear Drush's cache.

Once the sub-theme has been created you can begin customizing the sub-theme. The file structure for the sub-theme mirrors the file structure Drupal recommends to make it easy to find the files and functions you want to edit. The only main difference is where common theme functions are located, which is discussed in the next section.

Theme functions

Common themeing functions have been split up and placed into relative include files in order to make it easier to locate a function you wish to edit/create. All theme functions (template_preprocess_HOOK(), hook_HOOK_alter(), theme_HOOK(), etc.) can be found under the includes directory of the sub-theme.

Sub-theme includes directory structure:

|-includes
|  |-alter.inc
|  |-preprocess.inc
|  |-process.inc
|  |-theme.inc

The filename of each include file makes it easy to understand which themeing functions are located where. Common functions you will utilize during development already exist in some of these files, although they are commented out by default.

<?php
To enable the use of these functions, simply change:
  * Implements hook_theme().
 *
/* -- Delete this line if you want to use this function
function amazing_name_theme($existing, $type, $theme, $path) {
}
//
?>

to:

  *Implements hook_theme().
 /
function amazing_name_theme($existing, $type, $theme, $path) {
}

Be sure to clear the cache in order for the function you uncommented to be recognized by Drupal.

To learn more about what you can do with your UIkit sub-theme, read the Themeing Drupal 8 documentation guide.

Add new comment

Filtered HTML

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.

Log in