Semantic UI — User Guide

Semantic UI is a front-end framework that lets you build responsive layouts using human-friendly HTML. Instead of memorizing cryptic utility classes, you describe interface elements the way you would in plain English: <div class="ui three column grid">, <button class="ui primary button">, <div class="ui floating dropdown">. The framework turns that shared vocabulary into styled, themeable, and (for interactive widgets) scriptable UI.

This guide covers everything an application developer needs to install Semantic UI, use its 50+ components, drive its JavaScript widgets, and customize its look through the theming system. It is written against the Semantic UI 2.5.0 source.

Note

Semantic UI ships two kinds of components. Elements, Collections, and Views are pure CSS — you style them by applying classes to your HTML. Modules and Behaviors add interactivity and require jQuery plus a small JavaScript initialization call. Knowing which is which (see The Semantic UI Vocabulary) is the single most useful mental model for this framework.

Table of Contents

1. Quick Start
2. Installation
3. The Semantic UI Vocabulary
4. Layout Fundamentals
5. Using CSS Components (Elements, Collections, Views)
6. Using JavaScript Modules
7. Behaviors: API, Form Validation, Visibility
8. Theming and Customization
9. Building Your Own Bundle
10. Right-to-Left (RTL) Support
11. Accessibility & Browser Support
12. Troubleshooting
13. FAQ
14. Component Reference

1. Quick Start

The fastest way to try Semantic UI is to load the precompiled CSS and JavaScript from a CDN. You only need three things: the Semantic UI stylesheet, jQuery, and the Semantic UI script.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <!-- Semantic UI stylesheet -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/semantic-ui@2.5.0/dist/semantic.min.css">
</head>
<body>

  <div class="ui container">
    <h1 class="ui header">Hello, Semantic UI</h1>

    <button class="ui primary button">Primary</button>
    <button class="ui button">Secondary</button>

    <div class="ui pointing below label">A label</div>
  </div>

  <!-- jQuery must load BEFORE semantic.js -->
  <script src="https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/semantic-ui@2.5.0/dist/semantic.min.js"></script>
</body>
</html>

Open the file in a browser and you have a styled page. Everything visible above is pure CSS — no JavaScript was needed yet.

To add an interactive widget, apply the markup and then initialize it from script:

<div class="ui selection dropdown">
  <input type="hidden" name="fruit">
  <i class="dropdown icon"></i>
  <div class="default text">Select Fruit</div>
  <div class="menu">
    <div class="item" data-value="apple">Apple</div>
    <div class="item" data-value="orange">Orange</div>
    <div class="item" data-value="banana">Banana</div>
  </div>
</div>

<script>
  $('.ui.dropdown').dropdown();
</script>

Important

jQuery must be loaded before semantic.min.js. Semantic UI's interactive modules are jQuery plugins ($.fn.dropdown, $.fn.modal, …); if jQuery is not present first, you will see $(...).dropdown is not a function in the console.

Tip

The CDN approach is perfect for prototypes and learning. For production apps where you want a smaller, customized stylesheet, install the source and build only the components you use — see Installation and Building Your Own Bundle.

2. Installation

Semantic UI is distributed through several packages, each suited to a different workflow. Pick the one that matches how much customization you need.

There are also community integration packages for Ember (ember install semantic-ui-ember), Meteor (meteor add semantic:ui for LESS or meteor add semantic:ui-css for CSS), and Bower (bower install semantic-ui).

Note

Semantic UI has official React, Angular, Meteor, and Ember integrations maintained as separate repositories. If you are using React, you most likely want Semantic UI React rather than this package directly, because it wraps the components as native React components instead of requiring manual jQuery initialization.

2.1 Installing the full source (with build tools)

npm install semantic-ui

The package runs an interactive installer (a Gulp task) the first time it is installed. The installer asks where your project root is, where to place Semantic UI inside it, and which components to include. You will be offered three setup modes:

Automatic

Uses default locations and all components. Best for getting started.

? Set-up Semantic UI
  ❯ Automatic (Use default locations and all components)
    Express (Set components and output folder)
    Custom (Customize all src/dist values)

Express

Lets you choose which components to bundle and where the compiled output goes.

Custom

Full control over every source and destination path. Best for monorepos and unusual layouts.

After installation you build the framework with Gulp:

# Build all CSS/JS into dist/
gulp build

# Watch source files and rebuild on change (use while designing)
gulp watch

Building Semantic
✔ Building CSS
✔ Building Javascript
✔ Building Assets
✔ Compiling Themes

Tip

While you are designing your UI, run gulp watch and edit your theme files — the CSS rebuilds automatically. Once your UI is stable, you can rely on the compiled packages in dist/ and stop running the build.

2.2 Installing the precompiled CSS package

If you do not need theming, the CSS package is the lowest-friction option:

npm install semantic-ui-css

// In your app entry point
import 'semantic-ui-css/semantic.min.css';
import $ from 'jquery';
import 'semantic-ui-css/semantic.min.js';

Warning

When bundling semantic-ui-css with webpack / create-react-app, you may need loaders for the CSS @import and for the icon font files. A bare import of semantic.min.css can fail with Module parse failed: Unexpected character '@' if no css-loader is configured (see Troubleshooting, GitHub #6771 and #7073).

2.3 Requirements

3. The Semantic UI Vocabulary

Semantic UI organizes everything into five categories. Understanding the categories tells you immediately whether a component needs JavaScript and how to customize it.

3.1 How classes work

Almost every component starts with the class ui, followed by variations and the component name:

<button class="ui large red right floated button">Button</button>
<!--       │   │     │   │            │          └ component
           │   │     │   │            └ variation: floats right
           │   │     │   └ variation: alignment
           │   │     └ color
           │   └ size
           └ Semantic UI namespace -->

Variations are adjectives applied in any order: sizes (mini, tiny, small, large, huge, massive), colors (red, orange, yellow, olive, green, teal, blue, violet, purple, pink, brown, grey, black), and states (active, disabled, loading).

Tip

Read the class list left-to-right as a sentence: ui large red button → "a UI, large, red button." This is the "shared vocabulary" the framework's name refers to, and it is why you can often guess the right markup without consulting the reference.

3.2 States

Most components understand a common set of state classes:

4. Layout Fundamentals

4.1 Containers

A ui container is a responsive, centered fixed-width wrapper for page content. Use it to keep text and components at a comfortable reading width.

<div class="ui container">
  <p>Centered, responsive content.</p>
</div>

Variations: text container (narrower, optimized for prose), fluid container (full width).

4.2 The Grid

The ui grid is a flexbox-based column system. Semantic UI grids divide a row into up to 16 columns (configurable). Column counts are spelled out as words.

<div class="ui three column grid">
  <div class="column">One</div>
  <div class="column">Two</div>
  <div class="column">Three</div>
</div>

Explicit widths and rows:

<div class="ui grid">
  <div class="four wide column">Sidebar (4/16)</div>
  <div class="twelve wide column">Main (12/16)</div>
</div>

Responsive widths let columns change span by device:

<div class="ui stackable grid">
  <div class="sixteen wide mobile eight wide tablet four wide computer column">
    Responsive column
  </div>
</div>

Note

The stackable variation makes a grid collapse to a single column on mobile — the most common responsive pattern. Grids rely on flexbox, so they do not render correctly on IE9.

4.3 Menus

ui menu is a Collection used for navigation bars, tabs, and toolbars:

<div class="ui menu">
  <a class="active item">Home</a>
  <a class="item">Messages</a>
  <a class="item">Friends</a>
  <div class="right menu">
    <a class="item">Logout</a>
  </div>
</div>

5. Using CSS Components (Elements, Collections, Views)

CSS components require no JavaScript — you simply apply classes. This section shows the most common ones. The full list is in the Component Reference.

5.1 Buttons (Element)

<button class="ui button">Standard</button>
<button class="ui primary button">Primary</button>
<button class="ui red basic button">Red Basic</button>
<button class="ui loading button">Loading</button>
<button class="ui disabled button">Disabled</button>

<!-- Icon button -->
<button class="ui icon button"><i class="heart icon"></i></button>

<!-- Button group -->
<div class="ui buttons">
  <button class="ui button">One</button>
  <button class="ui button">Two</button>
</div>

5.2 Icons (Element)

Icons are a font. Apply <i class="NAME icon">:

<i class="user icon"></i>
<i class="big red heart icon"></i>
<i class="circular users icon"></i>

Caution

Icons render from a web font shipped in dist/themes/default/assets/fonts/. If your icons appear as empty boxes or the wrong glyphs, the font files are not being served at the path the CSS expects — the #1 Semantic UI integration bug. See Troubleshooting.

5.3 Inputs and Labels (Elements)

<div class="ui input">
  <input type="text" placeholder="Search...">
</div>

<div class="ui left icon input">
  <i class="search icon"></i>
  <input type="text" placeholder="Search...">
</div>

<a class="ui red label">Label</a>
<a class="ui blue tag label">Tag</a>

5.4 Segments and Headers (Elements)

<div class="ui segment">
  <h2 class="ui header">A Heading</h2>
  <p>Content inside a raised, bordered box.</p>
</div>

<div class="ui raised segment">Raised</div>
<div class="ui loading segment">Shows a spinner</div>

5.5 Forms (Collection)

<form class="ui form">
  <div class="field">
    <label>Name</label>
    <input type="text" name="name">
  </div>
  <div class="two fields">
    <div class="field">
      <label>Email</label>
      <input type="email" name="email">
    </div>
    <div class="field">
      <label>Password</label>
      <input type="password" name="password">
    </div>
  </div>
  <div class="field">
    <div class="ui checkbox">
      <input type="checkbox" name="agree">
      <label>I agree to the terms</label>
    </div>
  </div>
  <button class="ui primary submit button" type="submit">Submit</button>
</form>

Error/success states are applied to the form or individual fields: <form class="ui error form"> reveals ui error message blocks; <div class="field error"> highlights one field.

5.6 Tables (Collection)

<table class="ui celled striped table">
  <thead>
    <tr><th>Name</th><th>Status</th></tr>
  </thead>
  <tbody>
    <tr><td>Alice</td><td class="positive">Active</td></tr>
    <tr><td>Bob</td><td class="negative">Inactive</td></tr>
  </tbody>
</table>

Variations: celled, striped, selectable, sortable, definition, very basic, compact.

5.7 Messages (Collection)

<div class="ui info message">
  <i class="close icon"></i>
  <div class="header">Heads up!</div>
  <p>This is an informational message.</p>
</div>

<div class="ui positive message">Saved successfully.</div>
<div class="ui negative message">Something went wrong.</div>

Tip

The <i class="close icon"> makes the message dismissible — but only if you wire up the transition module to hide it. Pure CSS draws the X; the close behavior needs JavaScript (see Modules).

5.8 Views: Cards, Feeds, Comments

<div class="ui card">
  <div class="image"><img src="avatar.jpg"></div>
  <div class="content">
    <div class="header">Jane Doe</div>
    <div class="meta">Joined 2024</div>
    <div class="description">A short bio.</div>
  </div>
  <div class="extra content">
    <i class="user icon"></i> 42 Friends
  </div>
</div>

6. Using JavaScript Modules

Modules are interactive widgets implemented as jQuery plugins. They all follow the same two-part API, which is the key thing to learn once and reuse everywhere.

6.1 The dual API

Part 1 — Initialize (optionally with settings):

$('.ui.dropdown').dropdown();                 // init with defaults
$('.ui.modal').modal({ blurring: true });     // init with settings

Part 2 — Invoke behaviors by passing a method name as a string:

$('.ui.modal').modal('show');                 // call a behavior
$('.ui.modal').modal('hide');
$('.ui.dropdown').dropdown('clear');
$('.ui.accordion').accordion('toggle', 0);    // behavior with argument

Read and change settings at runtime:

var debug = $('.ui.modal').modal('setting', 'debug');        // read
$('.ui.modal').modal('setting', 'closable', false);          // write

Important

Every module supports 'destroy' (remove all bound events and instance data), 'setting' (get/set a setting), and 'refresh' (re-cache DOM references). These universal behaviors are in addition to each module's own methods.

6.2 Settings every module shares

Each module exposes a settings object (e.g. $.fn.dropdown.settings). A common core is present on all of them:

You override settings at init time, globally via $.fn.MODULE.settings, or per-call with the 'setting' behavior.

Tip

When a module "isn't working," set debug: true and verbose: true at init. Semantic UI's modules print a detailed, human-readable trace of every internal step to the console — it is the fastest way to see why an event didn't fire.

6.3 Dropdown

The most feature-rich module. Works on <select> elements, custom menus, multi-select, search, tagging, and remote (API) data.

<div class="ui selection dropdown">
  <input type="hidden" name="country">
  <i class="dropdown icon"></i>
  <div class="default text">Country</div>
  <div class="menu">
    <div class="item" data-value="us">United States</div>
    <div class="item" data-value="ca">Canada</div>
  </div>
</div>

$('.ui.dropdown').dropdown({
  clearable: true,
  onChange: function(value, text, $choice) {
    console.log('Selected', value);
  }
});

Selected key settings:

Callbacks: onChange, onAdd, onRemove, onLabelSelect, onLabelCreate, onLabelRemove, onNoResults, onShow, onHide.

Common behaviors:

$('.ui.dropdown').dropdown('set selected', 'ca');
$('.ui.dropdown').dropdown('get value');
$('.ui.dropdown').dropdown('clear');
$('.ui.dropdown').dropdown('restore defaults');

6.4 Modal

<div class="ui modal">
  <i class="close icon"></i>
  <div class="header">Confirm</div>
  <div class="content"><p>Are you sure?</p></div>
  <div class="actions">
    <div class="ui deny button">No</div>
    <div class="ui positive button">Yes</div>
  </div>
</div>

$('.ui.modal')
  .modal({
    closable: false,
    onApprove: function() { /* user clicked a positive button */ },
    onDeny:    function() { /* user clicked a deny button */ }
  })
  .modal('show');

Behaviors: show, hide, toggle, refresh, setting, destroy. Callbacks: onShow, onVisible, onHide, onHidden, onApprove, onDeny, onStart, onComplete.

Note

The modal automatically creates a dimmer behind itself. onApprove/onDeny return false to prevent the modal from closing — useful for validating before dismiss.

6.5 Popup

<button class="ui button" data-content="Helpful hint" data-position="top center">
  Hover me
</button>

$('.ui.button').popup();
// or fully from script:
$('.ui.button').popup({
  content: 'Created from JS',
  position: 'right center',
  on: 'click'   // 'hover' (default), 'click', 'focus', 'manual'
});

Behaviors: show, hide, toggle, destroy. Callbacks: onCreate, onShow, onVisible, onHide, onHidden, onRemove, onUnplaceable.

6.6 Accordion

<div class="ui accordion">
  <div class="title"><i class="dropdown icon"></i> Section 1</div>
  <div class="content"><p>First panel.</p></div>
  <div class="title"><i class="dropdown icon"></i> Section 2</div>
  <div class="content"><p>Second panel.</p></div>
</div>

$('.ui.accordion').accordion();
$('.ui.accordion').accordion('open', 0);   // open by index
$('.ui.accordion').accordion('toggle', 1);

Callbacks: onOpen, onOpening, onClose, onClosing, onChange, onChanging.

6.7 Tab

<div class="ui top attached tabular menu">
  <a class="active item" data-tab="first">First</a>
  <a class="item" data-tab="second">Second</a>
</div>
<div class="ui bottom attached active tab segment" data-tab="first">First content</div>
<div class="ui bottom attached tab segment" data-tab="second">Second content</div>

$('.menu .item').tab();
$.tab('change tab', 'second');   // programmatic switch

Callbacks: onLoad, onFirstLoad, onRequest, onSuccess, onVisible. Tabs can lazy-load remote HTML when apiSettings is supplied.

6.8 Checkbox, Dimmer, Sidebar, and the rest

$('.ui.checkbox').checkbox();           // styled checkbox/radio/toggle/slider
$('.ui.dimmer').dimmer('show');         // overlay
$('.ui.sidebar').sidebar('toggle');     // off-canvas navigation
$('.ui.sticky').sticky();               // pin element while scrolling
$('.ui.progress').progress({ percent: 60 });
$('.ui.rating').rating();               // star rating
$('.ui.embed').embed();                 // lazy video embed (YouTube/Vimeo)
$('.ui.shape').shape();                 // 3D shape transitions
$('.ui.nag').nag();                     // cookie/notice bar

The transition module powers all show/hide animations and can be called directly:

$('.message').transition('fade');
$('.box').transition('scale in', 500);   // animation + duration (ms)

A complete table of every module, its callbacks, and its purpose is in the Component Reference.

7. Behaviors: API, Form Validation, Visibility

Behaviors are JavaScript helpers that attach to elements but have no CSS component of their own.

7.1 API

The api behavior standardizes AJAX requests with templated URLs, loading states, and a full callback lifecycle. Many modules (dropdown, search, tab) use it internally, but you can use it directly:

$('.ui.button').api({
  action: 'follow user',          // named endpoint from settings.api map
  // or:
  url: '/users/{id}/follow',
  urlData: { id: 42 },
  method: 'POST',
  onSuccess: function(response) { /* ... */ },
  onFailure: function(response) { /* server returned failure */ },
  onError:   function(errorMessage) { /* network/HTTP error */ }
});

Callbacks: onRequest, onResponse, onSuccess, onComplete, onFailure, onError, onAbort. A button with an api attached automatically shows a loading state while the request is in flight.

7.2 Form Validation

The form behavior validates fields against a rules object and toggles error styling.

$('.ui.form').form({
  fields: {
    email: {
      identifier: 'email',
      rules: [{ type: 'empty', prompt: 'Enter your email' },
              { type: 'email', prompt: 'Enter a valid email' }]
    },
    password: {
      identifier: 'password',
      rules: [{ type: 'minLength[6]', prompt: 'At least 6 characters' }]
    }
  },
  onSuccess: function(event, fields) { /* all rules passed */ },
  onFailure: function(formErrors, fields) { return false; }
});

Callbacks: onValid, onInvalid, onSuccess, onFailure. Built-in rule types include empty, email, length[n], minLength[n], exactLength[n], integer, decimal, number, regExp, match[field], different[field], url, and more.

7.3 Visibility

The visibility behavior fires callbacks as elements scroll into and out of the viewport — used for lazy-loading images, infinite scroll, and scroll-triggered animations.

$('.image').visibility({
  type: 'image',          // lazy-load images
  transition: 'fade in',
  duration: 1000
});

$('.section').visibility({
  once: false,
  onBottomVisible: function() { /* load more */ }
});

Callbacks include onOnScreen, onOffScreen, onTopVisible, onBottomVisible, onPassing, onPassed, onTopPassed, onBottomPassed (and their …Reverse variants), onFixed, onUnfixed, onLoad, onAllLoaded.

8. Theming and Customization

Theming is Semantic UI's headline feature — the README describes it as "a UI framework designed for theming." Customization is done by editing LESS variables, never by overriding compiled CSS with !important.

8.1 The three levels of inheritance

Every component's final styling is resolved by layering three sources, in order:

1. Default theme   (src/themes/default/…)   ← Semantic's neutral baseline
2. Packaged theme  (src/themes/<name>/…)    ← e.g. 'github', 'material', 'amazon'
3. Site theme      (src/site/…)             ← YOUR overrides (highest priority)

Later levels override earlier ones. You almost never touch the default theme; you select a packaged theme per component and put your tweaks in the site theme.

8.2 Selecting themes with theme.config

theme.config (created by renaming theme.config.example) maps each component to a theme. The default maps everything to 'default':

/* Elements */
@button      : 'default';
@input       : 'default';

/* Modules */
@dropdown    : 'default';
@modal       : 'default';

To give buttons the GitHub look while keeping everything else default, change one line:

@button      : 'github';

Rebuild (gulp build) and your buttons now use the github packaged theme. Semantic UI ships 23 packaged themes, including amazon, material, bootstrap3, github, twitter, instagram, flat, and classic (full list in the Reference).

8.3 Customizing variables in the site theme

To change colors, fonts, or sizing globally, edit site/globals/site.variables. Important global variables:

/* site/globals/site.variables */
@fontName     : 'Inter';
@emSize       : 16px;
@primaryColor : @teal;

To tweak a single component, edit its file in your site theme — e.g. site/elements/button.variables:

/* site/elements/button.variables */
@verticalPadding   : 1em;
@horizontalPadding : 2em;
@borderRadius      : 0;   /* square buttons */

For CSS rules that no variable exposes, add them to the matching .overrides file (e.g. site/elements/button.overrides), which has access to all of that component's variables.

Important

The Google Fonts import is on by default (@importGoogleFonts: true). This makes the browser fetch Lato from fonts.googleapis.com at runtime. For privacy/offline/CSP-restricted apps, set @importGoogleFonts: false and self-host the font (see Troubleshooting, #7146).

8.4 Using a single primary color across the palette

Because everything derives from a small set of named colors (@blue, @red, @green, …) and @primaryColor, changing one or two variables re-skins the whole framework consistently — buttons, labels, active menu items, focused inputs, and more all follow.

9. Building Your Own Bundle

When you install the full semantic-ui package you get a Gulp build that compiles your themed LESS into dist/.

The build emits both a combined bundle and per-component files in dist/components/ (e.g. dropdown.css, dropdown.js, dropdown.min.css). This lets you import only the components you use:

<link rel="stylesheet" href="dist/components/button.min.css">
<link rel="stylesheet" href="dist/components/grid.min.css">
<script src="dist/components/dropdown.min.js"></script>

Tip

Importing only the components you use is the simplest way to shrink Semantic UI's footprint. The full default semantic.min.css includes every component and the icon font; a typical app uses a fraction of them.

To import LESS directly without the Gulp pipeline, copy theme.config.example to theme.config, rename _site/ to site/, then in your own LESS:

/* Import everything */
@import 'src/semantic';

/* Or one component (note the required & {} scope) */
& { @import 'src/definitions/elements/button'; }

Warning

The source LESS files do not contain vendor prefixes. If you compile the LESS yourself (instead of using the Gulp build), you must run autoprefixer as part of your build, or styles may break in older browsers.

10. Right-to-Left (RTL) Support

Semantic UI can produce a fully mirrored RTL build for languages such as Arabic and Hebrew.

• Choose RTL during the interactive installer, or set "rtl": true in semantic.json.
• Run gulp build (or gulp rtl) to generate the mirrored stylesheet.
• The build uses gulp-rtlcss to flip directional properties automatically.

Note

Some components have known RTL edge cases — for example, the sidebar toggle in certain RTL builds (GitHub #3236). Test interactive modules specifically after switching to RTL.

11. Accessibility & Browser Support

Browser support

Caution

Grids and other flexbox-based components are not supported on IE9 and may render incorrectly. Some non-layout components degrade gracefully on IE9, but flexbox layout does not.

Accessibility notes

• Modules add ARIA-relevant attributes and keyboard handling (e.g. dropdown supports keyboard navigation; allowTab controls tab-index insertion).
• Form fields should always have associated <label> elements.
• Some complex widgets (notably multiple-search dropdowns) have known screen-reader gaps reported upstream (GitHub #7125). Test with your target assistive technology and supplement with ARIA where needed.

12. Troubleshooting

Error: $(...).dropdown is not a function

Cause: jQuery is missing or loaded after semantic.js, or a module's per-component JS wasn't included. Solution: Load jQuery before Semantic UI's script. If using per-component files, include dist/components/dropdown.js. Prevention: Keep script order jquery → semantic everywhere.

Icons show as empty boxes or wrong glyphs

Cause: The icon web font (in themes/default/assets/fonts/) is not being served at the path the compiled CSS references — extremely common with bundlers and custom asset paths. Solution: Ensure the themes/ assets folder ships alongside semantic.css, or configure your bundler's font loader / @fontPath to match where you serve fonts. Prevention: When using webpack/Vite, add a file/asset loader for .woff, .woff2, .ttf, .eot, .svg.

Error: Module parse failed: Unexpected character '@'

Cause: Importing semantic.min.css (which begins with an @import for Google Fonts) through a bundler with no CSS loader configured (GitHub #6771). Solution: Add css-loader/style-loader (webpack) or the equivalent so .css @import statements are handled. Prevention: Configure CSS handling before importing the stylesheet from JS.

Errors mentioning googleProtocol, googleFonts, googleRequests

Cause: Google Fonts auto-import is enabled and the font request is failing or blocked (GitHub #7146). Solution: Set @importGoogleFonts: false in site/globals/site.variables and self-host the font, or fix the network/CSP rule. Prevention: Disable the auto-import in privacy/offline/CSP-restricted environments.

semantic-ui-css fails inside create-react-app / webpack

Cause: Missing loaders for CSS @import and font assets (GitHub #7073). Solution: Import the CSS through a configured CSS loader and provide font loaders; or use Semantic UI React instead of the raw CSS package in React apps. Prevention: Prefer the framework-native integration package for your framework.

Error: This module requires ui transitions

Cause: A module that animates (dropdown, modal, dimmer) was loaded without the transition module. Solution: Include the transition component (it is part of the full bundle; if you build per-component, add transition.js). Prevention: When hand-picking components, always include transition.

Modal does not appear / page won't scroll after closing a modal

Cause: Known mobile-browser and scroll-lock edge cases (GitHub #5341, #7153). Solution: Initialize the modal with detachable: true (default) and ensure no CSS leaves body with a lingering dimmable dimmed / scrolling class. Call .modal('hide') explicitly rather than removing the element. Prevention: Let the modal manage body state; don't manually toggle dimmer classes.

Installation fails (npm install semantic-ui)

Cause: The post-install Gulp wizard requires a compatible Node/Gulp; older Node or Gulp 3 fails (GitHub #7131, #7115). Solution: Use Node 18+ and Gulp 4. If you don't need theming, install semantic-ui-css instead (no build). Prevention: Match the documented Node/Gulp versions before installing the full package.

13. FAQ

Q: Do I need jQuery? Only for the interactive Modules and Behaviors (dropdown, modal, popup, form validation, etc.). Pure-CSS Elements, Collections, and Views work with zero JavaScript.

Q: What's the difference between semantic-ui and semantic-ui-css? semantic-ui is the full source with LESS and the Gulp build, for theming. semantic-ui-css is the precompiled default-theme output with no build step.

Q: I use React. Should I use this package? Most React developers should use Semantic UI React, a separate official package that wraps components as React components, avoiding manual jQuery initialization.

Q: How do I change the primary color everywhere at once? Set @primaryColor (and optionally the named color variables) in site/globals/site.variables, then rebuild. The change cascades to all components.

Q: How do I make the build smaller? Build and import only the per-component files in dist/components/ for the components you actually use, instead of the full semantic.min.css.

Q: Why are my icons missing? The icon web font isn't being served at the path the CSS expects. Ship the themes/ assets next to your CSS or configure a font loader. See Troubleshooting.

Q: Can I use Semantic UI without a build step at all? Yes — link dist/semantic.min.css and dist/semantic.min.js from a CDN with jQuery. You get the default theme and all components.

Q: How do I switch a single component to a packaged theme? Edit that component's line in theme.config (e.g. @button: 'material';) and rebuild.

Q: Is Semantic UI actively maintained? The 2.5.0 release (Oct 2022) modernized the build for Node 18 / Gulp 4. Development cadence has slowed and the project's future has been discussed openly (GitHub #7108). Evaluate the activity and community forks before adopting it for a long-lived new project.

Q: How do callbacks like onApprove cancel an action? Return false from onApprove/onDeny (modal) or onFailure (form) to prevent the default close/submit.

Q: Can dropdowns load options from a server? Yes. Pass apiSettings to the dropdown; it uses the api behavior to fetch and render remote results, with optional client-side filtering and sessionStorage caching.

14. Component Reference

14.1 CSS components (no JavaScript)

14.2 JavaScript modules and their callbacks

14.3 Behaviors (JS-only)

14.4 Universal module behaviors

Available on every module via $('.ui.MODULE').MODULE('behavior', …):

14.5 Packaged themes (src/themes/)

amazon, basic, bookish, bootstrap3, chubby, classic, colored, default, duo, fixed-width, flat, github, gmail, instagram, material, pulsar, raised, resetcss, round, rtl, striped, timeline, twitter.