0
# insert-css
1

2
insert-css is a lightweight JavaScript utility for dynamically inserting CSS strings directly into the HTML document head. It provides cross-browser compatibility and flexible positioning options for programmatic stylesheet injection.
3

4
## Package Information
5

6
- **Package Name**: insert-css
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install insert-css`
10

11
## Core Imports
12

13
```javascript
14
var insertCss = require('insert-css');
15
```
16

17
Alternative access:
18

19
```javascript
20
var insertCss = require('insert-css').insertCss;
21
```
22

23
## Basic Usage
24

25
```javascript
26
var insertCss = require('insert-css');
27

28
// Basic CSS insertion
29
var styleElement = insertCss('body { background: blue; }');
30

31
// CSS insertion with options
32
var styleElement = insertCss('body { color: red; }', {
33
  container: document.querySelector('#app'),
34
  prepend: true
35
});
36
```
37

38
## Capabilities
39

40
### CSS Insertion
41

42
Inserts a CSS string into the DOM, creating or reusing style elements as needed.
43

44
```javascript { .api }
45
/**
46
 * Insert CSS string into the DOM
47
 * @param {string} css - CSS string to insert (required)
48
 * @param {Object} options - Configuration options (optional)
49
 * @param {HTMLElement} options.container - Target container element, defaults to document.querySelector('head')
50
 * @param {boolean} options.prepend - If true, inserts CSS at top of container instead of bottom
51
 * @returns {HTMLElement} The style element that was created or reused
52
 * @throws {Error} If css parameter is undefined
53
 */
54
function insertCss(css, options);
55
```
56

57
**Key Features:**
58

59
- **Cross-browser compatibility**: Automatically handles IE's `styleSheet.cssText` vs modern browsers' `textContent`
60
- **UTF-8 BOM handling**: Strips UTF-8 BOM characters from CSS strings automatically
61
- **Style element reuse**: Efficiently reuses existing style elements for the same container/position combination
62
- **Flexible positioning**: Control insertion at top (prepend) or bottom (append) of container
63
- **Custom containers**: Insert CSS into any DOM element, not just the document head
64

65
**Usage Examples:**
66

67
```javascript
68
var insertCss = require('insert-css');
69

70
// Insert CSS into head (default behavior)
71
insertCss('body { margin: 0; padding: 0; }');
72

73
// Prepend CSS for higher priority (useful for library defaults)
74
insertCss('.library-default { color: gray; }', { prepend: true });
75

76
// Insert CSS into custom container
77
var appContainer = document.querySelector('#app');
78
insertCss('.app-styles { font-family: Arial; }', { 
79
  container: appContainer 
80
});
81

82
// The returned style element can be stored for reference
83
var myStyleElement = insertCss('p { line-height: 1.4; }');
84
console.log(myStyleElement.tagName); // 'STYLE'
85
```
86

87
**Error Handling:**
88

89
The function throws an Error if the `css` parameter is undefined:
90

91
```javascript
92
try {
93
  insertCss(); // throws Error
94
} catch (error) {
95
  console.log(error.message); // 'insert-css: You need to provide a CSS string. Usage: insertCss(cssString[, options]).'
96
}
97
```
98

99
## Types
100

101
```javascript { .api }
102
/**
103
 * Options object for configuring CSS insertion behavior
104
 */
105
interface InsertCssOptions {
106
  /** Target container element, defaults to document.querySelector('head') */
107
  container?: HTMLElement;
108
  /** If true, inserts CSS at top of container instead of bottom */
109
  prepend?: boolean;
110
}
111
```
112

113
## Browser Compatibility
114

115
- Internet Explorer 6+
116
- Chrome 20+
117
- Firefox 10+
118
- Safari (latest)
119
- Opera 11.0+
120
- Mobile: iPhone 6, iPad 6
121

122
## Dependencies
123

124
- **Runtime**: Zero dependencies
125
- **Environment**: Browser (requires `document` object)