Getting Started

Setting up Semantic UI build tools

Getting Semantic UI

For links to download Semantic UI, check our our download page.

Semantic uses command-line tools to build your project while theming. After getting Semantic, you will need to install nodejs and gulp to run the build process.




Installing node on OSX is easiest with homebrew

brew install node

Node on Linux should be installed to work without sudo. You can do that by using one of these techniques.

I personally use this set-up procedure:

mkdir ~/local echo 'export PATH=$HOME/local/bin:$PATH' >> ~/.bashrc . ~/.bashrc git clone git:// cd node ./configure --prefix=~/local make install git clone git:// cd npm make install

Windows install just requires downloading the node binary


After installing Node, Gulp can be installed globally using Node Package Manager (NPM)

npm install -g gulp

Project Dependencies

Node dependencies are managed per project in a special file package.json to make installing a project's depencies easy.

Once you're up and running. Navigate to the semantic directory and install the npm dependencies.

# install semantic dependencies npm install


Running Installer

Semantic uses gulp to compile your stylesheets when your theme changes. The first time you run gulp you will be greeted with an interactive installer

# install gulp

The installer will let you select which components to include, and specify paths for your project.

Installation Type
Automatic Installation will use the default paths, outputing css files to dist/ and packaging all components together
Express Will let you move your site folder and your dist folder and select from a list of components to include in your concatenated release.
Custom Will prompt you for all available options

The install process will create two files: semantic.json stores paths for your build and sits on the top-level of your project, theme.config is a LESS file that exists in src/ and allows you to centrally set the themes for each UI component.

The installer will also create a special folder which contains your site-specific themes. The default location for this is src/site. For more information on using site themes, see our customization guide.

Manual Install

If you prefer these files and folders can be moved manually instead of using the installer.

mv semantic.json.example semantic.json mv src/theme.config.example src/theme.config mv src/_site src/site vi semantic.json # modify paths vi src/theme.config # modify paths

Upgrading Semantic

You can use normal package manager functions to update your project, just be sure to re-install semantic after upgrading. Re-install will extend your semantic.json but not overwrite it

The method for updating Semantic will depend on your package manager, but in all cases just involves updating your source files and re-running the gulp installer

For a full list of settings for semantic.json, check the defaults values which it inherits from.

Using Semantic Build Tools

Gulp commands

After setting up your project you have access to several commands for building your css and javascript.

gulp # runs default task (watch) gulp watch # watches files for changes gulp build # builds all files from source gulp install # re-runs install

Semantic creates minified, and uncompressed files in your source for both individual components, and the components specified for your packaged version.

Keep in mind semantic will automatically adjust URLs in CSS and add vendor-prefixes as part of the build process. This means definitions and theme files do not need vendor prefixes.


Building and watching Semantic is only necessary while adjusting your UI. This is usually the first part of building a new project, and a separate process than building-out pages in your site.

During this architecting phase you can try downloading different themes, adjusting your site-wide settings (font-family, colors, etc) and tweaking components in your site's component overrides.

Files in the examples/ folder of your project can be useful for testing out changes in your UI. For example, you might run gulp watch download a new theme to src/site/themes/ then adjust your theme.config file with the name of the new theme and refresh examples/kitchensink.html to inspect changes in the theme.

You will only need to use Semantic's build tools while refining your UI, while designing pages you can rely on the compiled css and js in dist/ and your software stack's normal build set-up.

gulp watch will automatically recompile only the necessary definition files when you update semantic.config or any .variables or .overrides file.

Running Docs Locally

One useful way to track ui modifications for a team is to run a local instance of the UI docs to serve as a team "styleguide".

You can grab the doc source from GitHub.

git clone npm update # run server docpad run

The easiest setup is to keep semantic ui source and the docs source in adjacent directories and use Gulp to serve files to the docs.

Gulp includes two special commands for serving files to a second location

gulp serve-docs # watches for changes only gulp build-docs # builds all files to docs
The default directory path is ../docs. You can set-up a different location for serving docs by adjusting values in tasks/admin/docs.json
Next: Customizing Semantic

Dimmer Message
Dimmer sub-header