0
# PostCSS Focus Within
1

2
PostCSS Focus Within enables the use of the `:focus-within` pseudo-class in CSS by providing both a PostCSS transformation plugin and a browser polyfill. The plugin transforms CSS containing `:focus-within` selectors into equivalent attribute and class-based fallbacks, while the browser polyfill dynamically applies these fallbacks in browsers that don't support the native selector.
3

4
## Package Information
5

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

11
## Core Imports
12

13
PostCSS Plugin (ESM):
14

15
```javascript
16
import postcssFocusWithin from "postcss-focus-within";
17
// Also available as named export:
18
import postcssFocusWithin, { pluginOptions } from "postcss-focus-within";
19
```
20

21
PostCSS Plugin (CommonJS):
22

23
```javascript
24
const postcssFocusWithin = require("postcss-focus-within");
25
```
26

27
Browser Polyfill (ESM):
28

29
```javascript
30
import focusWithin from "postcss-focus-within/browser";
31
```
32

33
Browser Global Polyfill:
34

35
```html
36
<script src="https://unpkg.com/postcss-focus-within@9.0.1/dist/browser-global.js"></script>
37
<script>focusWithinInit()</script>
38
```
39

40
## Basic Usage
41

42
```javascript
43
import postcss from "postcss";
44
import postcssFocusWithin from "postcss-focus-within";
45

46
// PostCSS transformation
47
const result = await postcss([
48
  postcssFocusWithin({
49
    preserve: true,
50
    replaceWith: "[focus-within]",
51
    disablePolyfillReadyClass: false
52
  })
53
]).process(css);
54

55
// Browser polyfill initialization
56
import focusWithin from "postcss-focus-within/browser";
57
focusWithin({ replaceWith: "[focus-within]" });
58
```
59

60
CSS transformation example:
61

62
```css
63
/* Input CSS */
64
.my-form-field:focus-within label {
65
  background-color: yellow;
66
}
67

68
/* Output CSS */
69
.my-form-field[focus-within].js-focus-within label, 
70
.js-focus-within .my-form-field[focus-within] label {
71
  background-color: yellow;
72
}
73
.my-form-field:focus-within label {
74
  background-color: yellow;
75
}
76
```
77

78
## Architecture
79

80
PostCSS Focus Within is built around two complementary components:
81

82
- **PostCSS Plugin**: Transforms CSS at build time, creating fallback selectors for browsers without native support
83
- **Browser Polyfill**: Provides runtime behavior by dynamically managing focus state attributes/classes on DOM elements
84
- **Validation Utilities**: Ensures replacement selectors are valid for single-element application
85
- **Cross-environment Support**: Works in Node.js (PostCSS) and browsers (polyfill) with multiple module formats
86

87
## Capabilities
88

89
### PostCSS Plugin
90

91
PostCSS transformation plugin that converts `:focus-within` pseudo-selectors into compatible attribute/class selectors with polyfill-ready class prefixing.
92

93
```javascript { .api }
94
/**
95
 * Creates PostCSS plugin instance for transforming :focus-within selectors
96
 * @param options - Plugin configuration options
97
 * @returns PostCSS plugin object
98
 */
99
function postcssFocusWithin(options?: pluginOptions): Plugin;
100

101
interface pluginOptions {
102
  /** Preserve the original notation. Default: true */
103
  preserve?: boolean;
104
  /** The replacement class/attribute to be used in the polyfill. Default: "[focus-within]" */
105
  replaceWith?: string;
106
  /** Disable the selector prefix that prevents flash of incorrectly styled content. Default: false */
107
  disablePolyfillReadyClass?: boolean;
108
}
109
```
110

111
[PostCSS Plugin](./postcss-plugin.md)
112

113
### Browser Polyfill
114

115
Browser polyfill that provides :focus-within behavior by dynamically applying attributes or classes to elements when their descendants receive focus.
116

117
```javascript { .api }
118
/**
119
 * Initialize the focus-within polyfill in the browser
120
 * @param options - Polyfill configuration options
121
 */
122
function focusWithin(options?: BrowserOptions): void;
123

124
interface BrowserOptions {
125
  /** Force polyfill to run even if browser supports :focus-within. Default: false */
126
  force?: boolean;
127
  /** The replacement selector (class or attribute). Default: "[focus-within]" */
128
  replaceWith?: string;
129
}
130
```
131

132
[Browser Polyfill](./browser-polyfill.md)
133

134
## Types
135

136
```javascript { .api }
137
interface pluginOptions {
138
  /** Preserve the original notation. Default: true */
139
  preserve?: boolean;
140
  /** The replacement class/attribute to be used in the polyfill. Default: "[focus-within]" */
141
  replaceWith?: string;
142
  /** Disable the selector prefix that prevents flash of incorrectly styled content. Default: false */
143
  disablePolyfillReadyClass?: boolean;
144
}
145

146
interface BrowserOptions {
147
  /** Force polyfill to run even if browser supports :focus-within. Default: false */
148
  force?: boolean;
149
  /** The replacement selector (class or attribute). Default: "[focus-within]" */
150
  replaceWith?: string;
151
}
152
```