Build Tools
Using Gulp with Fomantic UI


30 Second Explanation

Download Fomantic UI navigate to the install folder then run a gulp command.

To build all files:

npx gulp build

To watch for changes

npx gulp watch

Why Build Tools?

Fomantic UI uses Gulp for several reasons:

Process LESS files with theming variables
Add vendor prefixes for supported browsers with autoprefixer
Watch file changes and rebuild the necessary files when adjusting themes
Automatically process asset paths, so that minified and concatenated releases can exist in different directories
Allow custom builds with only the required components for your site
Allow advanced usage like Right-To-Left (RTL) languages using RTLCSS

Folder Structure

A Fomantic UI project includes the following folder structure.

Your site's theme
Default theme
Additional themes
Config file for setting packaged themes
Compiled CSS and JS files
Individual component CSS and JS
concatenated release
concatenated release
Contains build settings for gulp

Gulp Commands

Below is a list of all available gulp commands

Command Description
install Asks install questions to setup semantic.json
watch (default) Watches for changes in source files, and builds file on change
build Build all files
clean Cleans dist/ folder
version Outputs current version
build-javascript Build JS files
build-css Build CSS files
build-assets Build assets files
serve-docs Serves files to local docs instance
build-docs Builds files to docs folder

Configuration Files


Build tool settings are stored in a special file called semantic.json It can be included in any folder that is in a parent folder of the fomantic install folder.

If you used the npm or meteor, a semantic.json file is automatically generated for you in the root of your project. If you used a different package manager you can run gulp install to run the interactive installer.

{ // base path added to all other paths specified in "paths" "base": "", // current version of Fomantic UI "version": "2.9.3", "paths": { "source": { // source theme.config "config" : "src/theme.config", // source definition folder "definitions" : "src/definitions/", // source site theme "site" : "src/site/", // source themes folder "themes" : "src/themes/" }, "output": { // packaged source (both compressed/uncompressed) "packaged" : "dist/", // uncompressed source "uncompressed" : "dist/components/", // compressed source "compressed" : "dist/components/", // output directory for theme assets "themes" : "dist/themes/" }, // directory for gulp clean task "clean" : "dist/" }, // when set to an integer permission, will set dist files with this file permission "permission" : false, // whether gulp watch/build should run RTLCSS "rtl": false, // will only include components with these names "components": [ "reset", "site", "button", "container", "divider", "flag", "header", "icon", "image", "input", "label", "list", "loader", "rail", "reveal", "segment", "step", "breadcrumb", "form", "grid", "menu", "message", "table", "ad", "card", "comment", "feed", "item", "statistic", "accordion", "checkbox", "dimmer", "dropdown", "embed", "modal", "nag", "popup", "progress", "rating", "search", "shape", "sidebar", "sticky", "tab", "transition", "api", "state", "visibility", "text", "calendar", "slider", "toast", "emoji" ], // generate .css/.js files for individual components (under /dist/components), but exclude them from semantic.css and semantic.js "individuals": [ "form", "modal", "step", "emoji" ], // Use custom postcss/autoprefixer options object "prefix": {}, // Use a custom Banner on each generated js/css file "banner": "/* A custom central FUI Banner !!!\n Awesome Release! \n*/", // strip all top headers from each component inside the concatenated, non-minified, semantic.css/js "stripHeaders": true, // Custom placeholder values inside banner "header": { "year": "ALWAYS 2099 :)", "title": "Fomantic-UI Pro", "repository": "Not yet available", "url": "" }, // whether to include special project maintainer tasks "admin": false }


You can disable specific variations of components allowing you to generate CSS files which only contain features you require. This makes your custom distribution files much smaller in size

Most of the components also have a separate variable to decide which components should be rendered for which colors of your global color palette of colors.less or which sizes should be rendered.

// The defaults enable everything // In a custom theme you could only disable/adjust the variables you don't need in your own {component}.variables @variationButtonTertiary: false; // don't compile tertiary button styles @variationIconColors: red, green, batman; // only compile red and green as icon color options @variationImageSizes: small, huge; // only compile small and huge image sizes @variationSegmentColors: false; // don't compile any segment color styles @variationBreadcrumbSizes: false; // don't compile any breadcrumb size styles


You can modify/define the global color palette entirely by adjusting a single LESS Map @colors in a custom colors.less file.

Each color consists of a predefined set of properties used in all components. You can define whatever color name you want.

If you only want to reduce the used colors from the default palette, you may only adjust the related colors-list variables inside variation.variables instead of changing the colors.less file.
// limit all components to yellow, purple and green @variationAllColors: yellow, purple, green; // purple buttons, red labels, green messages and no colors for all other components @variationAllColors: false; @variationButtonColors: purple; @variationLabelColors: red; @variationMessageColors: green;
If you change the whole available colors like in the example below, make sure you also adjust the related colors-list variables inside variation.variables to avoid a build error.
@variationAllComponents: batman, spiderman;
// This example would only provide two custom colors "batman", "spiderman" // Your custom compiled build will contain all colorable components // like "ui batman button" or "ui spiderman label" @colors: { @batman: { color : @white; light : @grey; border : @grey; background : @black; header : #222222; boxShadow : @greyBoxShadow; boxFloatShadow : @greyBoxFloatingShadow; text : @white; lightText : @white; hoverText : @grey; focus : @white; lightFocus : @grey; down : @white; lightDown : @grey; active : #888866; lightActive : #888822; shadow : @greyTextShadow; lightShadow : @lightGreyTextShadow; hover : @grey; lightHover : @grey; ribbon : @greyRibbonShadow; invertedRibbon : @greyInvertedRibbonShadow; tertiary : @greyTertiaryColor; tertiaryHover : @greyTertiaryColorHover; tertiaryFocus : @greyTertiaryColorFocus; tertiaryActive : @greyTertiaryColorActive; bright : @white; brightHover : @grey; isDark : false; // 'true' will adjust light colors on non inverted variants isVeryDark : false; // 'true' will use black/white in certain color/background situations }; @spiderman: { color : @red; light : @lightRed; border : @lightRed; ... // and all the other properties as above }; };

The colors.less file also contains another central LESS Map @formStatesfor defining form states. Also here, you can define any form state name and its colors as you like.

// Your final custom compiled build will offer form components like // "ui excited input" or ".ui.form > .excited.message" @formStates: { @excited: { color: #880000; background: #ffcccc; borderColor: @red; borderRadius: 10px; boxShadow: @inputErrorBoxShadow; cornerLabelColor: @white; labelBackground: @lightRed; dropdownLabelColor: @red; dropdownLabelBackground: @lightRed; dropdownHoverBackground: @lightRed; dropdownSelectedBackground: @lightRed; dropdownActiveBackground: @lightRed; inputAutoFillBackground: @lightRed; inputAutoFillBorderColor: @red inputFocusBackground: @lightRed; inputFocusColor: @red; inputFocusBorderColor: #440000; inputFocusBoxShadow: @inputErrorFocusBoxShadow; inputPlaceholderColor: #660000; inputPlaceholderFocusColor: #550000; transparentBackground: @white; transparentColor: @red; }; };

Excluding components from main css/js file

By default, all components listed in semantic.json are added to semantic.css and semantic.js on build, but sometimes you don't need a component to be included on every page. To keep the file size of your main assets down, it's better to separate these components and reference them individually in your HTML.

To make this work, add these components to your semantic.json as "individuals" (see above example). Then the css/js files will still be generated/updated as usual under dist/components.

Note: You can specify only the individuals in semantic.json and leave the components list empty. The individuals are automatically excluded from the main components list.


LESS uses a special configuration file theme.config which lets you specify what theme each component should use. If you have not generated this file yet, you will receive an error message when running build tools

You can learn more about theme.config by checking out the theming guide

Importing Gulp Tasks

See our recipes section for examples on how to import individual gulp tasks into your custom Gulpfile.

Auto-Install & Continuous Integration

We've added a new setting to semantic.json in 2.2 to help make working with a CLI, or other automated deployments more streamlined.

Specifying autoInstall: true in an environments semantic.json configuration will prevent any user prompting when running npx gulp install allowing for automated deployment.

Dimmer Message
Dimmer sub-header