# @stylable/runtime

> Stylable runtime DOM integration

Latest version **6.1.1** (published 2024-05-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @stylable/runtime
pnpm add @stylable/runtime
yarn add @stylable/runtime
bun add @stylable/runtime
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.1.1 |
| Published | 2024-05-30 |
| First published | 2018-08-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.12.0 |
| Dependencies | 0 |
| Unpacked size | 57.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1274 |
| Author | Wix.com |
| Maintainers | tomrav, avi.vahl, idoros, baraki, cijoe, alexswix |

## Links

- npm: https://www.npmjs.com/package/@stylable/runtime
- Repository: https://github.com/wix/stylable.git#master
- Homepage: https://github.com/wix/stylable/tree/master#readme
- Issues: https://github.com/wix/stylable/issues
- npm.io page: https://npm.io/package/@stylable/runtime

## Recent versions

- 6.1.1 (latest) — 2024-05-30
- 5.19.0 (release-5.x) — 2024-03-05
- 6.0.0-rc.3 (next) — 2024-02-01
- 4.15.1 (release-4.x) — 2022-08-14
- 3.13.2 (release-3.x) — 2021-12-09
- 1.4.0 (release-1.x) — 2020-03-05
- 6.1.0 — 2024-05-21
- 6.0.2 — 2024-04-15
- 6.0.1 — 2024-03-19
- 6.0.0 — 2024-03-13
- 5.18.1 — 2024-02-12
- 5.18.0 — 2024-01-14
- 5.17.0 — 2023-12-03
- 6.0.0-rc.2 — 2023-11-08
- 6.0.0-rc.1 — 2023-11-08
- … 180 more at https://npm.io/package/@stylable/runtime/versions

## README

# @stylable/runtime

[![npm version](https://img.shields.io/npm/v/@stylable/runtime.svg)](https://www.npmjs.com/package/@stylable/runtime)

`@stylable/runtime` provides the utility that is used to create the stylesheet functions that apply `classNames` and `states` to the DOM. It also exposes an optional DOM renderer that is responsible for loading CSS in its correct order.

End-users will usually not add this package directly as a dependency themselves, and would instead receive it as a dependency of their chosen integration (e.g. `@stylable/webpack-plugin`).

## Usage

`@stylable/runtime` exposes two methods, `Stylesheet` and `Renderer`.

### Stylesheet

When importing a Stylable stylesheet, there are multiple named exports that are exposed for usage.

```ts 
import { 
    style, 
    classes, 
    vars, 
    stVars, 
    keyframes, 
    layers, 
    containers, 
    cssStates 
} from './local.st.css';
```

|Import name|Description|
|-----------|-----------|
|`style`|utility function that returns a string to be used as a node class name for classes and states passed to it |
|`classes`|an object mapping exported classes from their source name to their scoped name |
|`vars`|an object mapping exported css custom properties (vars) from their source name to their scoped name |
|`stVars`|an object mapping build time Stylable variables to their build time values (these cannot be overridden in runtime) |
|`keyframes`|an object mapping exported keyframes from their source name to their scoped name |
|`layers`|an object mapping exported layers from their source name to their scoped name |
|`containers`|an object mapping exported containers from their source name to their scoped name |
|`cssStates`|utility function that maps an object representing states and their values to a string with all required classes |

#### Style utility function

The `style` function is useful for creating the `root` node of you component, passing along classes passed through props, or whenever a state is being defined.

```ts
style(
    contextClassName: string, stateOrClass: string | StateMap, ...classes: string[]
)
```

|Argument|Type|Description|Required|
|---------|----|-----------|:------:|
|contextClassName|`string`|`className` to be namespaced|`true`|
|stateOrClass|`StateMap` \| `string`|either an object containing states and their values, or a class string|`false`|
|classes|`string`|any other argument passed will represent a classes that should be applied. In any root node of a component, props.className should be passed along to maintain external customization |`false`|

```tsx
import { style, classes } from './local.st.css';

// properties passed to the component externally
props = { className: "app__root app--propstate" };

// The classes export exposes a map of classNames and their namespaced values.
classes.root;
// returns "local__root"

<div className={style(classes.root)} />
// becomes <div className="local__root" /> 

<div className={style(classes.root, { localState: true })} />
// becomes <div className="local__root local--localstate" /> 

<div className={style(classes.root, { localState: true }, props.className)} />
// becomes <div className="local__root local--localstate app__root app--propstate" /> 

<div className={style(classes.root, 'global-class', props.className)} />
// becomes <div className="local__root global-class app__root app--propstate" /> 

<div className={classes.part} />
// becomes <div className="local__part" /> 
```

### Renderer

Responsible for managing CSS files, linking to the `document` and maintaining their correct order in your application.

## TypeScript integration
When importing a Stylable stylesheet in TypeScript, a global module declaration needs to be defined in order to not receive type errors about unknown imports.

Add the following file to your `/src` directory.
```ts
// globals.d.ts
declare module '*.st.css' {
    export * from '@stylable/runtime/stylesheet';

    const defaultExport: unknown;
    export default defaultExport;
}
```

## License
Copyright (c) 2017 Wix.com Ltd. All Rights Reserved. Use of this source code is governed by a [MIT license](./LICENSE).

---
_Source: https://npm.io/package/@stylable/runtime · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._