@gmono/scoped-css-react

Scoped CSS hooks for regular React (CSR/SSR).

Built on @gmono/scoped-css-core, this package pre-binds the core hooks to the React adapter (ReactCssAdapter), so CSS written inside a component stays scoped to that component — no naming collisions, no global stylesheet ordering problems.

Install

npm install @gmono/scoped-css-react

Requires react >= 18 and @gmono/scoped-css-core >= 0.1.0.

Quick start

import { useCSS } from '@gmono/scoped-css-react'

export function Button({ children }: { children: React.ReactNode }) {
  const { classes, style } = useCSS(`
    .btn { padding: 0.5rem 1rem; border-radius: 6px; }
    .btn:hover { opacity: 0.9; }
  `)

  return (
    <>
      {style}
      <button className={classes.btn}>{children}</button>
    </>
  )
}

.btn is rewritten to .c3-btn (or similar), so two components can both define .btn without clashing.

Global styles

Pass { global: true } to opt out of scoping — class names are emitted as-is.

const { classes, style } = useCSS(`.alert { color: red; }`, { global: true })
// classes = { alert: 'alert' }

Sharing a scope with child components

A parent can publish its scope to the subtree; children inherit the prefix via useCSSClasses() or by using { scoped: true }.

import { useCSS, CSSMappingProvider, useCSSClasses } from '@gmono/scoped-css-react'

function Panel({ children }: { children: React.ReactNode }) {
  const { classes, style, scopeId } = useCSS(`.panel { border: 1px solid #ddd; }`)
  return (
    <>
      {style}
      <CSSMappingProvider mapping={{ scopeId, classes }}>
        <div className={classes.panel}>{children}</div>
      </CSSMappingProvider>
    </>
  )
}

function PanelTitle() {
  const parentClasses = useCSSClasses()
  return <h2 className={parentClasses?.title || 'title'}>Title</h2>
}

Importing CSS from files

useCSSFile is not available in the browser (files cannot be read synchronously). Instead, import the CSS as a string via your bundler's ?raw suffix and pass it to useCSS():

import btnCss from './button.css?raw'
import { useCSS } from '@gmono/scoped-css-react'

export function Button() {
  const { classes, style } = useCSS(btnCss)
  return <>{style}<button className={classes.btn}>Click</button></>
}

Advanced

CssMappingContext is re-exported for advanced use (testing, custom providers). Type helpers (CSSMapping, UseCSSOptions, CSSMappingProviderProps, UseCSSResult) are re-exported from @gmono/scoped-css-core.

License

MIT