# 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](#3-the-semantic-ui-vocabulary)) is the single most useful mental model for this framework.

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Installation](#2-installation)
3. [The Semantic UI Vocabulary](#3-the-semantic-ui-vocabulary)
4. [Layout Fundamentals](#4-layout-fundamentals)
5. [Using CSS Components (Elements, Collections, Views)](#5-using-css-components-elements-collections-views)
6. [Using JavaScript Modules](#6-using-javascript-modules)
7. [Behaviors: API, Form Validation, Visibility](#7-behaviors-api-form-validation-visibility)
8. [Theming and Customization](#8-theming-and-customization)
9. [Building Your Own Bundle](#9-building-your-own-bundle)
10. [Right-to-Left (RTL) Support](#10-right-to-left-rtl-support)
11. [Accessibility & Browser Support](#11-accessibility--browser-support)
12. [Troubleshooting](#12-troubleshooting)
13. [FAQ](#13-faq)
14. [Component Reference](#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.

```html
<!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:

```html
<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](#2-installation) and [Building Your Own Bundle](#9-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.

| Package | Install | What you get | Use when |
|---|---|---|---|
| **semantic-ui** | `npm install semantic-ui` | Full source + LESS + Gulp build tools + interactive installer | You want to theme/customize and build your own CSS |
| **semantic-ui-css** | `npm install semantic-ui-css` | Precompiled `semantic.css` / `semantic.js`, no build step | You want the default theme, fast |
| **semantic-ui-less** | `npm install semantic-ui-less` | LESS source only (bring your own build) | You compile LESS in your own pipeline |
| **less-plugin-semantic-ui** | `npm install less-plugin-semantic-ui` | LESS plugin form | Plugin-based LESS builds |
| CDN | — (link tag) | Default precompiled bundle | Prototypes, demos |

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)

```bash
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.

    ```text
    ? 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:

```bash
# Build all CSS/JS into dist/
gulp build

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

```text
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:

```bash
npm install semantic-ui-css
```

```javascript
// 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](#12-troubleshooting), GitHub #6771 and #7073).

### 2.3 Requirements

| Requirement | Detail |
|---|---|
| **jQuery** | `3.x` (the source pins `^3.5.1`). Required for all Modules and Behaviors. Pure-CSS components need no JavaScript. |
| **Node.js** | 18+ recommended for the build tools (2.5.0 was updated for Node 18). |
| **Gulp** | Gulp 4 (build tools were rewritten for Gulp 4 in 2.5.0). |
| **Browser** | See [Browser Support](#11-accessibility--browser-support). |

---

## 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.

| Category | What it is | Needs JS? | Examples |
|---|---|---|---|
| **Globals** | Page-wide resets and site settings | No | `reset`, `site` |
| **Elements** | Single, indivisible building blocks | No | `button`, `icon`, `input`, `label`, `header`, `image`, `segment` |
| **Collections** | Groups of elements used together | No | `form`, `grid`, `menu`, `table`, `message`, `breadcrumb` |
| **Views** | Higher-level content presentations | No | `card`, `comment`, `feed`, `item`, `statistic`, `ad` |
| **Modules** | Interactive widgets with behavior | **Yes** | `dropdown`, `modal`, `popup`, `accordion`, `tab`, `checkbox`, `sidebar` |
| **Behaviors** | JS-only helpers (no component of their own) | **Yes** | `api`, `form` (validation), `visibility` |

### 3.1 How classes work

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

```html
<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:

| State | Meaning |
|---|---|
| `active` | Currently selected / open |
| `disabled` | Non-interactive, dimmed |
| `loading` | Shows a spinner overlay (buttons, segments, dimmers) |
| `error` / `success` / `warning` | Validation / status styling (forms, messages) |

---

## 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.

```html
<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.

```html
<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:

```html
<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:

```html
<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:

```html
<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](#14-component-reference).

### 5.1 Buttons (Element)

```html
<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">`:

```html
<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](#12-troubleshooting).

### 5.3 Inputs and Labels (Elements)

```html
<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)

```html
<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)

```html
<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)

```html
<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)

```html
<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](#6-using-javascript-modules)).

### 5.8 Views: Cards, Feeds, Comments

```html
<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):

```javascript
$('.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:

```javascript
$('.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:

```javascript
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:

| Setting | Default | Purpose |
|---|---|---|
| `silent` | `false` | Suppress all console output |
| `debug` | `false` | Log internal events to the console |
| `verbose` | `false` | Extra-detailed debug logging |
| `performance` | `true` | Log a performance trace of internal calls |
| `name` | (module) | Human name used in debug logs |
| `namespace` | (module) | Event namespace used to bind/unbind |

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.

```html
<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>
```

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

Selected key settings:

| Setting | Default | Purpose |
|---|---|---|
| `on` | `'click'` | Event that opens the menu |
| `action` | `'activate'` | What happens on item selection (`activate`, `select`, `combo`, `hide`, function) |
| `allowAdditions` | `false` | Let users add values not in the list (tagging) |
| `maxSelections` | `false` | Cap the number of selections (multi-select) |
| `fullTextSearch` | `false` | Match anywhere in the text (`'exact'` for exact) |
| `apiSettings` | `false` | Pull options from a remote endpoint (uses the `api` behavior) |
| `clearable` | `false` | Show a clear (×) control |
| `placeholder` | `'auto'` | Convert blank `<select>` value to placeholder text |

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

Common behaviors:

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

### 6.4 Modal

```html
<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>
```

```javascript
$('.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

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

```javascript
$('.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

```html
<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>
```

```javascript
$('.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

```html
<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>
```

```javascript
$('.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

```javascript
$('.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:

```javascript
$('.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](#14-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:

```javascript
$('.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.

```javascript
$('.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.

```javascript
$('.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:

```text
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'`:

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

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

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

```less
@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](#14-component-reference)).

### 8.3 Customizing variables in the site theme

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

| Variable | Default | Controls |
|---|---|---|
| `@emSize` | `14px` | The single base size everything scales from |
| `@fontSize` | `14px` | Body text size |
| `@fontName` | `'Lato'` | Primary font family |
| `@primaryColor` | `@blue` | Primary brand color |
| `@secondaryColor` | `@black` | Secondary brand color |
| `@importGoogleFonts` | `true` | Whether to auto-load the font from Google Fonts |

```less
/* 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`:

```less
/* 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](#12-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/`.

| Command | What it does |
|---|---|
| `gulp build` | Compile all components → `dist/semantic.css`, `dist/semantic.js`, minified variants, and per-component files |
| `gulp watch` | Rebuild affected files whenever source changes (development) |
| `gulp build-css` | Build only stylesheets |
| `gulp build-javascript` | Build only scripts |
| `gulp clean` | Remove the `dist/` output |
| `gulp rtl` | Produce right-to-left builds |

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:

```html
<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:

```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

| Browser | Supported versions |
|---|---|
| Firefox / Chrome / Safari (Mac) | Last 2 versions |
| Internet Explorer | 11+ |
| Microsoft Edge | 12+ |
| Android | 4.4+ (Chrome for Android 44+) |
| iOS Safari | 7+ |

> [!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](#12-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)

| Category | Components |
|---|---|
| **Globals** | `reset`, `site` |
| **Elements** | `button`, `container`, `divider`, `flag`, `header`, `icon`, `image`, `input`, `label`, `list`, `loader`, `placeholder`, `rail`, `reveal`, `segment`, `step` |
| **Collections** | `breadcrumb`, `form`, `grid`, `menu`, `message`, `table` |
| **Views** | `ad`, `card`, `comment`, `feed`, `item`, `statistic` |

### 14.2 JavaScript modules and their callbacks

| Module | Purpose | Callbacks |
|---|---|---|
| `accordion` | Collapsible panels | `onOpen`, `onOpening`, `onClose`, `onClosing`, `onChange`, `onChanging` |
| `checkbox` | Styled checkbox / radio / toggle / slider | `onChange`, `onChecked`, `onUnchecked`, `onIndeterminate`, `onDeterminate`, `onEnable`, `onDisable` |
| `dimmer` | Content overlay | `onShow`, `onHide`, `onChange`, `onStart`, `onComplete` |
| `dropdown` | Select / multi-select / search / tagging / remote | `onChange`, `onAdd`, `onRemove`, `onLabelSelect`, `onLabelCreate`, `onLabelRemove`, `onNoResults`, `onShow`, `onHide` |
| `embed` | Lazy video embeds (YouTube/Vimeo) | `onCreate`, `onDisplay`, `onPlaceholderDisplay`, `onEmbed`, `onPlay`, `onPause`, `onStop`, `onReset` |
| `modal` | Dialog with dimmer | `onShow`, `onVisible`, `onHide`, `onHidden`, `onApprove`, `onDeny`, `onStart`, `onComplete` |
| `nag` | Dismissible notice/cookie bar | (state-persistence module; no callbacks) |
| `popup` | Tooltips / popovers | `onCreate`, `onShow`, `onVisible`, `onHide`, `onHidden`, `onRemove`, `onUnplaceable` |
| `progress` | Progress bars | `onChange`, `onSuccess`, `onWarning`, `onError`, `onActive`, `onNumeric`, `onLabelUpdate` |
| `rating` | Star ratings | `onRate` |
| `search` | Autocomplete / live search | `onSelect`, `onResults`, `onResultsAdd`, `onSearchQuery`, `onResultsOpen`, `onResultsClose`, `onSuccess`, `onError`, `onFailure`, `onAbort`, `onComplete`, `onText`, `onURL` |
| `shape` | 3D shape transitions | `onChange` |
| `sidebar` | Off-canvas navigation | `onShow`, `onVisible`, `onHide`, `onHidden`, `onChange` |
| `sticky` | Pin element during scroll | `onStick`, `onUnstick`, `onTop`, `onBottom`, `onScroll`, `onReposition` |
| `tab` | Tabbed navigation (with optional lazy load) | `onLoad`, `onFirstLoad`, `onRequest`, `onSuccess`, `onVisible` |
| `transition` | Animation engine for show/hide | `onStart`, `onShow`, `onHide`, `onComplete` |

### 14.3 Behaviors (JS-only)

| Behavior | Purpose | Callbacks |
|---|---|---|
| `api` | AJAX with templated URLs + loading states | `onRequest`, `onResponse`, `onSuccess`, `onComplete`, `onFailure`, `onError`, `onAbort` |
| `form` | Field validation | `onValid`, `onInvalid`, `onSuccess`, `onFailure` |
| `visibility` | Scroll/viewport events, lazy loading | `onOnScreen`, `onOffScreen`, `onTopVisible`, `onBottomVisible`, `onPassing`, `onPassed`, `onTopPassed`, `onBottomPassed` (+ `…Reverse`), `onFixed`, `onUnfixed`, `onLoad`, `onAllLoaded` |

### 14.4 Universal module behaviors

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

| Behavior | Effect |
|---|---|
| `'setting', name [, value]` | Get or set a setting at runtime |
| `'refresh'` | Re-cache DOM references |
| `'destroy'` | Unbind events and remove instance data |

### 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`.

---

_Generated June 2026 from Semantic-Org/Semantic-UI at 597843a. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._