@hyperfrontend/ui-utils/style

style

Dynamic CSS authoring helpers: per-element style application and runtime stylesheet management.

createApplyStyle and createApplyStyles produce reusable functions that apply a Style or StyleMap to one or many target elements, useful when the same style block is applied repeatedly. cssRule and cssRules build CSS rule strings from object literals; cssObjectToString is the lower-level converter from a Style object to its CSS representation. addStylesheet and removeStylesheet mount and unmount <style> elements at runtime, so dynamic themes and feature-flagged styles can be inserted without touching the DOM by hand.

API Reference§

ƒ Functions

§function

addStylesheet(css: string | StyleMap, label?: string): [HTMLStyleElement, () => void]

Adds a new stylesheet to the document with optional label.
A label is only taken while its stylesheet is still in the document. If that element was removed by other means, the label is released and the new stylesheet takes it.

Parameters

Name	Type	Description
§css	`string \| StyleMap`	The CSS rules to be added in the new stylesheet
§label?	`string`	Optional label for the new stylesheet

Returns

[HTMLStyleElement, () => void]

A tuple where the first item is the created HTMLStyleElement, and the second item is a cleanup function

Examples

CSS string

const [styleElement, removeStyles] = addStylesheet(`
  .modal { display: flex; align-items: center; }
  .modal-overlay { background: rgba(0, 0, 0, 0.5); }
`, 'modal-styles')

// Remove when done
removeStyles()

StyleMap object

const [styleElement, removeStyles] = addStylesheet({
  '.button': { backgroundColor: '#3498db', padding: '10px 20px' },
  '.button:hover': { backgroundColor: '#2980b9' },
})

View source →

§function

createApplyStyle(selector: string, style: Style): (args: []) => [HTMLStyleElement, () => void]

Creates a run-once function that applies a single style rule to a selector.

Parameters

Name	Type	Description
§selector	`string`	CSS selector to apply the style to
§style	`Style`	Style object to apply

Returns

(args: []) => [HTMLStyleElement, () => void]

A function that applies the style when called

Example

Applying single style rule

const applyTooltipStyle = createApplyStyle('.tooltip', {
  position: 'absolute',
  backgroundColor: '#333',
  color: '#fff',
  padding: '4px 8px',
  borderRadius: '4px'
})

// Style is injected into document on first call
applyTooltipStyle()

// Subsequent calls are no-ops (style already applied)
applyTooltipStyle()

View source →

§function

createApplyStyles(styles: StyleMap): (args: []) => [HTMLStyleElement, () => void]

Creates a run-once function that applies multiple style rules.

Parameters

Name	Type	Description
§styles	`StyleMap`	StyleMap object containing selector-style pairs

Returns

(args: []) => [HTMLStyleElement, () => void]

A function that applies all styles when called

Example

Applying multiple style rules

const applyModalStyles = createApplyStyles({
  '.modal-overlay': {
    position: 'fixed',
    inset: '0',
    backgroundColor: 'rgba(0, 0, 0, 0.5)'
  },
  '.modal-content': {
    backgroundColor: '#fff',
    borderRadius: '8px',
    padding: '24px'
  }
})

// All rules injected on first call
applyModalStyles()

View source →

§function

cssObjectToString(cssObj: Style): string

Converts a CSS object into a CSS string suitable for inline styles or style sheets. Automatically converts camelCase properties to kebab-case.

Parameters

Name	Type	Description
§cssObj	`Style`	The CSS object with property-value pairs

Returns

string

A CSS string representation

Example

Converting style object to CSS

const styles = {
  backgroundColor: '#f0f0f0',
  fontSize: '14px',
  marginTop: '8px'
}

cssObjectToString(styles)
// => 'background-color: #f0f0f0; font-size: 14px; margin-top: 8px; '

View source →

§function

cssRule(selector: string, css: string | Partial<CSSStyleDeclaration>): string

Generates a CSS rule string from a given selector and style declaration.
This function takes a CSS selector and either a string or a CSSStyleDeclaration object representing the styles to be applied. It validates the selector and converts the CSS object to a string if needed. The function then constructs and returns a valid CSS rule as a string.

Parameters

Name	Type	Description
§selector	`string`	The CSS selector to which the styles will be applied
§css	`string \| Partial<CSSStyleDeclaration>`	The styles to apply, either as a string or CSSStyleDeclaration object

Returns

string

A string representing a complete CSS rule

Examples

With style object

cssRule('.button', { padding: '8px 16px', borderRadius: '4px' })
// => '.button{padding: 8px 16px; border-radius: 4px}'

With CSS string

cssRule('.button:hover', 'background-color: #007bff; color: white')
// => '.button:hover{background-color: #007bff; color: white}'

View source →

§function

cssRules(styles: StyleMap): string

Creates CSS rules from a styles object, converting each selector-style pair into CSS rule strings.

Parameters

Name	Type	Description
§styles	`StyleMap`	An object mapping CSS selectors to style objects

Returns

string

A string containing all CSS rules separated by newlines

Example

Creating CSS rules from object

const styles = {
  '.card': { padding: '16px', boxShadow: '0 2px 4px rgba(0,0,0,0.1)' },
  '.card-title': { fontSize: '18px', fontWeight: 'bold' }
}

cssRules(styles)
// => '.card{padding: 16px; box-shadow: 0 2px 4px rgba(0,0,0,0.1)}\n.card-title{font-size: 18px; font-weight: bold}'

View source →

§function

removeStylesheet(ref: string | HTMLStyleElement): void

Removes a stylesheet from the document.

Parameters

Name	Type	Description
§ref	`string \| HTMLStyleElement`	The label or the HTMLStyleElement of the stylesheet to be removed.

Examples

By label

addStylesheet('.theme { color: red; }', 'theme-styles')
removeStylesheet('theme-styles')

By element reference

const [styleElement] = addStylesheet('.custom { margin: 0; }')
removeStylesheet(styleElement)

View source →

◈ Interfaces

§interface

StyleMap

Map of style names to style values or CSS declarations

View source →

◆ Types

§type

Style

Partial CSS style declaration for inline styling

type Style = Partial<CSSStyleDeclaration>

View source →