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:
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
A Fomantic UI project includes the following folder structure.
Config file for setting packaged themes
Compiled CSS and JS files
Individual component CSS and JS
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 |
semantic.json
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": "https://fomantic-ui.com/pro"
},
// whether to include special project maintainer tasks
"admin": false
}
variation.variables
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
colors.less
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.
theme.config
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.
