CSS Utilities API reference for CSS utility functions palette API 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

NameTypeDescription
cssstringThe CSS string to adopt
adoptedElementDocument | ShadowRootThe document or shadow root to adopt the stylesheet to. Defaults to document
optionsobjectOptional configuration
Options
NameTypeDefaultDescription
hashstring | numberauto-generatedHash value for the CSS content used for deduplication
cacheStylesheetbooleantrueWhether 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

NameTypeDescription
selectorstringThe CSS selector to match (case-insensitive, supports substring matching)
sourcestring | Document | CSSStyleSheet | CSSStyleSheet[]The source to extract from. Defaults to document
optionsobjectOptional configuration
Options
NameTypeDefaultDescription
returnTextbooleanfalseReturn CSS text instead of CSSStyleSheet object
exactMatchbooleanfalseRequire 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

NameTypeDescription
cssstringThe CSS string to scope
scopeSelectorstringThe selector to use for scoping (case-insensitive). Defaults to empty string
optionsobjectOptional configuration
Options
NameTypeDefaultDescription
replaceHostbooleanfalseReplace :host and :host() selectors with the scope selector instead of prepending
appendToRootElementsbooleantrueAppend 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.