CSS UtilitiesAPI reference for CSS utility functionspaletteAPI Reference
Categories

CSS Utilities

The CSS utilities provide functions for working with stylesheets, including adoption to documents and shadow roots, extraction of rules, and scoping for component isolation.

Functions

adoptStylesheet

function adoptStylesheet(css, adoptedElement, { hash, cacheStylesheet } = {})

Adopts a CSS stylesheet to a document or shadow root with intelligent caching support to prevent duplicate stylesheets.

Parameters

Name Type Description
css string The CSS string to adopt
adoptedElement Document | ShadowRoot The document or shadow root to adopt the stylesheet to. Defaults to document
options object Optional configuration
Options
Name Type Default Description
hash string | number auto-generated Hash value for the CSS content used for deduplication
cacheStylesheet boolean true Whether to cache the stylesheet globally for reuse across shadow roots

Example

import { adoptStylesheet } from '@semantic-ui/utils';


// Basic adoption to document
adoptStylesheet('.button { color: blue; padding: 8px; }');


// Adopt to shadow root
const element = document.createElement('div');
const shadowRoot = element.attachShadow({ mode: 'open' });
adoptStylesheet(css, shadowRoot);


// Disable caching for one-time stylesheets
adoptStylesheet(tempCSS, document, { cacheStylesheet: false });

Performance Note Caching is enabled by default to prevent duplicate stylesheets when the same CSS is adopted to multiple shadow roots, which is common in component architectures.

extractCSS

function extractCSS(selector, source, { returnText } = {})

Extracts CSS rules matching a selector from various stylesheet sources using substring matching.

Parameters

Name Type Description
selector string The CSS selector to match (case-insensitive, supports substring matching)
source string | Document | CSSStyleSheet | CSSStyleSheet[] The source to extract from. Defaults to document
options object Optional configuration
Options
Name Type Default Description
returnText boolean false Return CSS text instead of CSSStyleSheet object
exactMatch boolean false Require exact selector matching. When false, allows substring matching

Returns

A new CSSStyleSheet containing matching rules, or CSS text string if returnText is true.

Example

import { extractCSS } from '@semantic-ui/utils';


// Extract from CSS string and return as text
const buttonCSS = extractCSS('.button', cssString, { returnText: true });
console.log(buttonCSS); // CSS text for debugging


// Extract from document stylesheets
const buttonSheet = extractCSS('.button');
console.log(`Found ${buttonSheet.cssRules.length} button rules`);


// Exact selector matching (no substring matching)
const exactMatch = extractCSS('.btn', cssString, { exactMatch: true });
// Only matches .btn, not .btn-primary or .btn-secondary


// Extract from multiple stylesheets
const widgetRules = extractCSS('.widget', [sheet1, sheet2]);

Matching Behavior Uses substring matching: .btn will match .btn-primary, .btn-secondary, etc.

scopeStyles

function scopeStyles(css, scopeSelector, { replaceHost, appendToRootElements } = {})

Scopes CSS rules by prepending a selector to all rules with configurable options for web component integration and root element handling.

Parameters

Name Type Description
css string The CSS string to scope
scopeSelector string The selector to use for scoping (case-insensitive). Defaults to empty string
options object Optional configuration
Options
Name Type Default Description
replaceHost boolean false Replace :host and :host() selectors with the scope selector instead of prepending
appendToRootElements boolean true Append scope to html/body selectors instead of prepending

Returns

The scoped CSS string with all rules modified according to the scoping strategy.

Example

import { scopeStyles } from '@semantic-ui/utils';


// Basic scoping - prepends .my-component to all selectors
const scoped = scopeStyles('.button { color: red; }', '.my-component');
// Result: .my-component .button { color: red; }


// Replace :host selectors for web component CSS porting
const hostCSS = ':host { display: block; } :host(.active) { opacity: 1; }';
const ported = scopeStyles(hostCSS, '.widget', { replaceHost: true });
// Result: .widget { display: block; } .widget.active { opacity: 1; }


// Handle root elements with prepending
const rootCSS = 'html { font-size: 16px; } body { margin: 0; }';
const rootScoped = scopeStyles(rootCSS, '.app', { appendToRootElements: false });
// Result: .app html { font-size: 16px; } .app body { margin: 0; }

Web Component Integration Use replaceHost: true when porting existing web component CSS to scoped styles. The function handles both :host and :host(.class) syntax correctly.