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:
echo 'export PATH=$HOME/local/bin:$PATH' >> ~/.bashrc
git clone git://github.com/joyent/node.git
git clone git://github.com/isaacs/npm.git
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
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
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
The installer will let you select which components to include, and specify paths for your project.
||Installation will use the default paths, outputing css files to
dist/ and packaging all components together
||Will let you move your site folder and your dist folder and select from a list of components to include in your concatenated release.
||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.
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
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
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
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 email@example.com:Semantic-Org/Semantic-UI-Docs.git
# run server
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
Next: Customizing Semantic