0
# JSS
1

2
JSS is a comprehensive CSS-in-JS library that enables developers to write styles using JavaScript objects and generate optimized CSS stylesheets at runtime. It provides a powerful plugin architecture with numerous plugins for features like nested selectors, camel case property names, vendor prefixing, default units, and more. The library supports both server-side rendering and client-side style injection, offers TypeScript support, and is designed for high performance with features like style caching and efficient DOM updates.
3

4
## Package Information
5

6
- **Package Name**: jss
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install jss`
10

11
## Core Imports
12

13
```javascript
14
import jss, { create, SheetsRegistry } from "jss";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const jss = require("jss").default;
21
const { create, SheetsRegistry } = require("jss");
22
```
23

24
## Basic Usage
25

26
```javascript
27
import jss from "jss";
28

29
// Create a stylesheet
30
const styles = {
31
  myButton: {
32
    color: 'green',
33
    '&:hover': {
34
      background: 'red'
35
    }
36
  }
37
};
38

39
const sheet = jss.createStyleSheet(styles);
40
sheet.attach();
41

42
// Access generated class names
43
console.log(sheet.classes.myButton); // "myButton-0-1-2"
44

45
// Use in HTML
46
document.getElementById('button').className = sheet.classes.myButton;
47
```
48

49
## Architecture
50

51
JSS is built around several key components:
52

53
- **JSS Instance**: The main orchestrator that creates stylesheets and manages plugins (`Jss` class)
54
- **StyleSheet**: Container for CSS rules with lifecycle management (attach/detach from DOM)
55
- **Rule System**: Seven rule types for different CSS constructs (style, keyframes, media queries, etc.)
56
- **Plugin Architecture**: Extensible system for transforming styles and adding features
57
- **Registry System**: Global and scoped management of multiple stylesheets
58
- **Renderer**: Abstraction layer for DOM manipulation and server-side rendering
59

60
## Capabilities
61

62
### JSS Instance Management
63

64
Core JSS instance creation and configuration for setting up the CSS-in-JS environment.
65

66
```javascript { .api }
67
function create(options?: Partial<JssOptions>): Jss;
68

69
interface Jss {
70
  createStyleSheet<Name extends string | number | symbol>(
71
    styles: Partial<Styles<Name, any, undefined>>,
72
    options?: StyleSheetFactoryOptions
73
  ): StyleSheet<Name>;
74
  removeStyleSheet(sheet: StyleSheet): this;
75
  setup(options?: Partial<JssOptions>): this;
76
  use(...plugins: Plugin[]): this;
77
  createRule(style: JssStyle, options?: RuleFactoryOptions): Rule;
78
  createRule<Name extends string>(name: Name, style: JssStyle, options?: RuleFactoryOptions): Rule;
79
}
80
```
81

82
[JSS Instance Management](./jss-instance.md)
83

84
### StyleSheet Operations
85

86
StyleSheet lifecycle management including creation, rule manipulation, and DOM attachment.
87

88
```javascript { .api }
89
interface StyleSheet<RuleName extends string | number | symbol = string | number | symbol> {
90
  classes: Classes<RuleName>;
91
  keyframes: Keyframes<string>;
92
  attach(): this;
93
  detach(): this;
94
  addRule(style: JssStyle, options?: Partial<RuleOptions>): Rule;
95
  addRule(name: RuleName, style: JssStyle, options?: Partial<RuleOptions>): Rule | null;
96
  addRules(styles: Partial<Styles<RuleName, any, undefined>>, options?: Partial<RuleOptions>): Rule[];
97
  getRule(nameOrSelector: RuleName | string): Rule;
98
  deleteRule(name: RuleName): boolean;
99
  update(name: string, data: object, options?: UpdateOptions): this;
100
  update(data: object, options?: UpdateOptions): this;
101
  toString(options?: ToCssOptions): string;
102
}
103
```
104

105
[StyleSheet Operations](./stylesheet.md)
106

107
### Sheet Registries
108

109
Global and scoped stylesheet management for organizing multiple stylesheets in applications.
110

111
```javascript { .api }
112
class SheetsRegistry {
113
  readonly index: number;
114
  add<RuleName extends string | number | symbol>(sheet: StyleSheet<RuleName>): void;
115
  reset(): void;
116
  remove<RuleName extends string | number | symbol>(sheet: StyleSheet<RuleName>): void;
117
  toString(options?: ToCssOptions): string;
118
}
119

120
class SheetsManager {
121
  readonly size: number;
122
  get(key: object): StyleSheet | null;
123
  add(key: object, sheet: StyleSheet): void;
124
  manage(key: object): StyleSheet | null;
125
  unmanage(key: object): void;
126
}
127

128
class RuleList {
129
  add(name: string, decl: JssStyle, options?: RuleOptions): Rule | null;
130
  get(nameOrSelector: string): Rule;
131
  remove(rule: Rule): void;
132
  indexOf(rule: Rule): number;
133
  update(name: string, data: {}): void;
134
  update(data: {}): void;
135
  toString(options?: ToCssOptions): string;
136
}
137
```
138

139
[Sheet Registries](./registries.md)
140

141
### Utility Functions
142

143
Helper functions for CSS value conversion, dynamic style extraction, and rule creation.
144

145
```javascript { .api }
146
function toCssValue(value: JssValue): string;
147
function getDynamicStyles(styles: Styles): Styles | null;
148
function createRule<D>(name: string, decl: JssStyle, options: RuleOptions): Rule;
149
function createGenerateId(options?: CreateGenerateIdOptions): GenerateId;
150
const hasCSSTOMSupport: boolean;
151
```
152

153
[Utility Functions](./utilities.md)
154

155
## Core Types
156

157
```javascript { .api }
158
// Base CSS property types from csstype package dependency
159
type CSSProperties<TValue = string | number> = import('csstype').Properties<TValue>;
160
type NormalCssProperties = CSSProperties<string | number>;
161
type NormalCssValues<K> = K extends keyof NormalCssProperties ? NormalCssProperties[K] : JssValue;
162

163
// Function type for dynamic styles
164
type Func<P, T, R> = T extends undefined ? (data: P) => R : (data: P & {theme: T}) => R;
165

166
// Observable interface for reactive values
167
interface MinimalObservable<T> {
168
  subscribe(nextOrObserver: ((value: T) => void) | {next: (value: T) => void}): {
169
    unsubscribe: () => void
170
  }
171
}
172

173
type JssStyle<Props = any, Theme = undefined> = {
174
  [K in keyof NormalCssProperties]:
175
    | NormalCssValues<K>
176
    | JssStyle<Props, Theme>
177
    | Func<Props, Theme, NormalCssValues<K> | JssStyle<undefined, undefined> | undefined>
178
    | MinimalObservable<NormalCssValues<K> | JssStyle | undefined>
179
} | {
180
  [K: string]:
181
    | JssValue
182
    | JssStyle<Props, Theme>
183
    | Func<Props, Theme, JssValue | JssStyle<undefined, undefined> | undefined>
184
    | MinimalObservable<JssValue | JssStyle | undefined>
185
};
186

187
type Styles<
188
  Name extends string | number | symbol = string,
189
  Props = unknown,
190
  Theme = undefined
191
> = Record<
192
  Name,
193
  | JssStyle<Props, Theme>
194
  | Array<JssStyle<Props, Theme>>
195
  | string
196
  | Func<Props, Theme, JssStyle<undefined, undefined> | string | null | undefined>
197
  | MinimalObservable<JssStyle | string | null | undefined>
198
>;
199

200
type Classes<Name extends string | number | symbol = string> = Record<Name, string>;
201

202
type JssValue = (string & {}) | (number & {}) | Array<string | number | Array<string | number> | '!important'> | null | false;
203

204
interface Plugin {
205
  onCreateRule?(name: string, decl: JssStyle, options: RuleOptions): Rule;
206
  onProcessRule?(rule: Rule, sheet?: StyleSheet): void;
207
  onProcessStyle?(style: JssStyle, rule: Rule, sheet?: StyleSheet): JssStyle;
208
  onProcessSheet?(sheet?: StyleSheet): void;
209
  onChangeValue?(value: string, prop: string, rule: Rule): string | null | false;
210
  onUpdate?(data: object, rule: Rule, sheet?: StyleSheet): void;
211
}
212

213
interface JssOptions {
214
  createGenerateId: CreateGenerateId;
215
  plugins: ReadonlyArray<Plugin>;
216
  Renderer?: {new (): Renderer} | null;
217
  insertionPoint: InsertionPoint;
218
  id: CreateGenerateIdOptions;
219
}
220

221
// Additional supporting types
222
type CreateGenerateId = (options?: CreateGenerateIdOptions) => GenerateId;
223
type GenerateId = (rule: Rule, sheet?: StyleSheet<string>) => string;
224
type InsertionPoint = string | HTMLElement | Comment;
225
type Keyframes<Name extends string = string> = Record<Name, string>;
226

227
interface CreateGenerateIdOptions {
228
  minify?: boolean;
229
}
230

231
interface RuleOptions {
232
  selector?: string;
233
  sheet?: StyleSheet;
234
  index?: number;
235
  parent?: ContainerRule | StyleSheet;
236
  classes: Classes;
237
  jss: Jss;
238
  generateId: GenerateId;
239
  Renderer: Renderer;
240
}
241

242
interface Rule {
243
  type: string;
244
  key: string;
245
  isProcessed: boolean;
246
  options: RuleOptions;
247
  toString(options?: ToCssOptions): string;
248
}
249

250
interface ContainerRule extends Rule {
251
  rules: RuleList;
252
}
253

254
interface StyleSheetFactoryOptions {
255
  media?: string;
256
  meta?: string;
257
  index?: number;
258
  link?: boolean;
259
  element?: HTMLStyleElement;
260
  generateId?: GenerateId;
261
  classNamePrefix?: string;
262
}
263

264
interface UpdateOptions {
265
  process?: boolean;
266
  force?: boolean;
267
}
268

269
interface ToCssOptions {
270
  indent?: number;
271
  format?: boolean;
272
  allowEmpty?: boolean;
273
}
274

275
interface Renderer {
276
  setProperty(cssRule: HTMLElement | CSSStyleRule, prop: string, value: JssValue): boolean;
277
  getPropertyValue(cssRule: HTMLElement | CSSStyleRule, prop: string): string;
278
  removeProperty(cssRule: HTMLElement | CSSStyleRule, prop: string): void;
279
  setSelector(cssRule: CSSStyleRule, selectorText: string): boolean;
280
  attach(): void;
281
  detach(): void;
282
  deploy(sheet: StyleSheet): void;
283
  insertRule(rule: Rule): false | CSSRule;
284
  deleteRule(cssRule: CSSRule): boolean;
285
  replaceRule(cssRule: CSSRule, rule: Rule): false | CSSRule;
286
  indexOf(cssRule: CSSRule): number;
287
  getRules(): CSSRuleList | void;
288
}
289
```