feat(runtime): custom `inject` function #3028

exside · 2023-08-24T11:26:33Z

First of all, amazing work with UnoCSS, keep it up!

I'm liking runtime, but one thing I'm missing is the ability to control where the generated styles get injected into the DOM, right now they are basically even before the head tag. I'm using it in a context where i'd like to override existing classes from HTML markup I don't control via UnoCSS shortcuts, but I can't (without !important) because the styles from that platform are in the head (as usual) and single class selector's specificity is therefore higher than single class shortcuts from UnoCSS defined/injected earlier on.

So the change is relatively simple, it's just a user configurable function that receives the style element and the user can then inject that wherever they want. Default behaviour doesn't change. Layering logic is untouched, the function just controls where the first layer is injected.

One can now do the following:

	window.__unocss = {
		...,
		runtime: {
			inject: (styleElement) => document.head.append(styleElement),
		},
	};

which results in:

If you don't like the way it's implemented or where, let me know, glad to adapt to your liking. Just threw this together for myself, but thought it might be helpful for others too.

netlify · 2023-08-24T11:26:47Z

❌ Deploy Preview for unocss failed.

Name	Link
🔨 Latest commit	`9df4bc2`
🔍 Latest deploy log	https://app.netlify.com/sites/unocss/deploys/64f0a1c3b3c3b40008093d23

chu121su12 · 2023-08-25T10:39:30Z

The insertion before <head> was done so that unocss styles can be overriden by other library/styles that usually appear in the <head> or even <body>.

Per your example,

The first <style> element can be overriden by unocss, especially if you are using reset/preflights.

You can get each layer's <style> element with the update() method and reposition them manually. See test example below.

unocss/test/runtime-dom.test.ts

Lines 32 to 42 in 1073bea

    
           const result = await runtime?.update() 
        
           const layers = [...(result?.getStyleElements().keys() ?? [])] 
        
           layers.forEach((layer) => { 
        
             const expected = `/* layer: ${layer} */` 
        
             expect(result?.css).toContain(expected) 
        
             const style = result?.getStyleElement(layer) 
        
             expect(style?.tagName).equals('STYLE') 
        
             expect(style?.innerHTML).toContain(expected) 
        
           })

chu121su12 · 2023-08-25T13:38:43Z

packages/runtime/src/index.ts

@@ -161,15 +162,15 @@ export default function init(inlineConfig: RuntimeOptions = {}) {
      styleElements.set(layer, styleElement)

      if (previousLayer == null) {
-        html().prepend(styleElement)
+        inject(styleElement)
      }
      else {
        const previousStyle = getStyleElement(previousLayer)
        const parentNode = previousStyle.parentNode
        if (parentNode)
          parentNode.insertBefore(styleElement, previousStyle.nextSibling)


This should be handled. Maybe use previousStyle/previousLayer for context

Not sure I undestand, I'm simply replacing the hardcoded html().prepend() with an optional custom method that prepends/appends/inserts the style element(s) wherever the user needs it? What do you mean by "should be handled"? (I mean if a runtime user uses this config option he/she should know what it does IMHO 😉 )

Ah maybe i get what you mean: You think we should give users the ability to inject each layer separately wherever they want it?

If that is what you are proposing, I think this would maybe add unnecessary complexity, no? I didn't want to mess with the existing logic of how UnoCSS injects the different layers etc., just WHERE in the DOM it does all of that.

chu121su12 · 2023-08-25T13:40:43Z

packages/runtime/src/index.ts

@@ -122,6 +122,7 @@ export default function init(inlineConfig: RuntimeOptions = {}) {

  runtimeOptions.configResolved?.(userConfig, userConfigDefaults)
  const uno = createGenerator(userConfig, userConfigDefaults)
+  const inject = (styleElement) => runtimeOptions.inject ? runtimeOptions.inject(styleElement) : html().prepend(styleElement)


Please add the type and some description

Added to RuntimeOptions interfarce

chu121su12 · 2023-08-25T13:43:44Z

packages/runtime/src/index.ts

@@ -161,15 +162,15 @@ export default function init(inlineConfig: RuntimeOptions = {}) {
      styleElements.set(layer, styleElement)

      if (previousLayer == null) {
-        html().prepend(styleElement)
+        inject(styleElement)


You may want to send layer for context

exside · 2023-08-25T18:30:11Z

The insertion before was done so that unocss styles can be overriden by other library/styles that usually appear in the or even .

absolutely agree! This is the normal use case, but in mine I want to use Uno CSS within a third party vendor platform that does a lot of things i can't control, including markup & styles etc., and here the issue is that I DON'T want the platform's styles to override my utils (or shortcuts) defined in Uno, of course I can use !important everywhere, but we all know that's bad practice and leads to lots of other issues, so simply being able to control where Uno's style elements are placed within the DOM can solve that problem.

You can get each layer's <style> element with the update() method and reposition them manually. See test example below.

yes, but that doesn't matter if the third party code does not use @layer at all 😉

packages/runtime/src/index.ts

Improve comment Co-authored-by: Anthony Fu <anthonyfu117@hotmail.com>

Add ability to control where unocss runtime styles are injected

4121c89

exside requested review from antfu and chu121su12 as code owners August 24, 2023 11:26

chu121su12 reviewed Aug 25, 2023

View reviewed changes

exside added 2 commits August 25, 2023 20:45

Add prop/type to RuntimeOptions interface

7ddf774

Make type more specific with HTMLStyleElement

d36de0d

exside requested a review from chu121su12 August 25, 2023 19:26

Merge branch 'main' into exside-patch-1

90572a9

chu121su12 approved these changes Aug 26, 2023

View reviewed changes

Merge branch 'main' into exside-patch-1

e00a93b

antfu reviewed Aug 28, 2023

View reviewed changes

packages/runtime/src/index.ts Show resolved Hide resolved

antfu changed the title ~~Add ability to control where unocss runtime styles are injected~~ feat(runtime): custom inject function Aug 28, 2023

Update packages/runtime/src/index.ts

2a22221

Improve comment Co-authored-by: Anthony Fu <anthonyfu117@hotmail.com>

antfu approved these changes Aug 29, 2023

View reviewed changes

Merge branch 'main' into exside-patch-1

9df4bc2

antfu merged commit 77ea190 into unocss:main Aug 31, 2023
0 of 10 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(runtime): custom `inject` function #3028

feat(runtime): custom `inject` function #3028

exside commented Aug 24, 2023 •

edited

netlify bot commented Aug 24, 2023 •

edited

chu121su12 commented Aug 25, 2023

chu121su12 Aug 25, 2023

exside Aug 25, 2023 •

edited

exside Aug 25, 2023 •

edited

chu121su12 Aug 25, 2023

exside Aug 25, 2023

chu121su12 Aug 25, 2023

exside commented Aug 25, 2023 •

edited

feat(runtime): custom inject function #3028

feat(runtime): custom inject function #3028

Conversation

exside commented Aug 24, 2023 • edited

netlify bot commented Aug 24, 2023 • edited

❌ Deploy Preview for unocss failed.

chu121su12 commented Aug 25, 2023

chu121su12 Aug 25, 2023

Choose a reason for hiding this comment

exside Aug 25, 2023 • edited

Choose a reason for hiding this comment

exside Aug 25, 2023 • edited

Choose a reason for hiding this comment

chu121su12 Aug 25, 2023

Choose a reason for hiding this comment

exside Aug 25, 2023

Choose a reason for hiding this comment

chu121su12 Aug 25, 2023

Choose a reason for hiding this comment

exside commented Aug 25, 2023 • edited

feat(runtime): custom `inject` function #3028

feat(runtime): custom `inject` function #3028

exside commented Aug 24, 2023 •

edited

netlify bot commented Aug 24, 2023 •

edited

exside Aug 25, 2023 •

edited

exside Aug 25, 2023 •

edited

exside commented Aug 25, 2023 •

edited