qwik-styled-ve

Qwik Styled Vanilla-Extract ⚡️💅

This provides a Styled-Components-like (SC) API in Qwik, using vanilla-extract (VE) and stylis. This combination yields a type-checked 0-runtime CSS-in-TS project.

Try it out now on 👉 StackBlitz 👈.

Example:

• styles.css.ts:

  import {styled} from 'qwik-styled-ve'
  
  export const RedText = styled.span`
    color: red;
  `
  

gets converted at build time to

• styles.css.ts.vanilla.css:

  .werasf1 {
    color: red;
  }
  

• styles.css.ts.vanilla.js:

  import './styles.css.ts.vanilla.css'
  import {styled as _spofw} from 'qwik-styled-vs/real-styled'
  
  export var RedText = _spofw('span', 'werasf1')
  

RedText is a Qwik Lite component ready for use, and the CSS will be included by Qwik automatically.

Type-checking happens automatically thanks to the fact that the source file is a .ts file (you can use plain js too) and all helpers have proper typing.

Installation

Install the needed NPM modules; they can be dev dependencies because Qwik will bundle them correctly for client and server.

npm i -D qwik-styled-ve @vanilla-extract/css

Then, add the Vite plugin to your vite.config.ts, for example:

import {defineConfig} from 'vite'
import {qwikVite} from '@builder.io/qwik/optimizer'
import {qwikCity} from '@builder.io/qwik-city/vite'
import tsconfigPaths from 'vite-tsconfig-paths'
// ---------------- ADD THIS ----------------
import {vanillaExtractPlugin} from 'qwik-styled-ve/vite'

export default defineConfig(() => {
  const cfg = {
    build: {sourcemap: true},
    plugins: [
      qwikCity(),
      qwikVite(),
      tsconfigPaths(),
      // ---------------- ADD THIS ----------------
      // This has to come somewhere after qwikVite, or the exports break
      vanillaExtractPlugin(),
    ],
  }
  return cfg
})

Usage

This library is complementary to vanilla-extract, so head over to the vanilla-extract docs to learn the basics.

styled

You use styled to create Qwik components that you can import. This uses the same configuration objects as the vanilla-extract style() function:

header.css.ts:

import {style, styled} from 'qwik-styled-ve'

// Local classname that makes things fancy
export const fancy = style({})

// Header: a Qwik Lite Component
export const Header = styled.header({
  padding: '0.5em',
  border: 'thin solid var(--color-hint)',
  borderBottom: 'none',
  selectors: {
    [`${fancy} &, ${fancy}&`]: {
      background: 'gold',
    },
  },
})

header.tsx:

import {Header, fancy} from './header.css'

export default component$(() => {
  // do header stuff
  return (
    <Header class={isFancy && fancy}>
      Header, possibly fancy.
      <br />
      The classname it uses is {Header.className}.
    </Header>
  )
})

css

There's also css template string helper to convert CSS syntax to vanilla-extract syntax. You can use it anywhere that accepts vanilla-extract style objects:

header.css.ts:

import {style, styled, css} from 'qwik-styled-ve'

// Local classname
export const fancy = style({})

// Header: a Qwik Lite Component
export const Header = styled.h1(css`
  padding: 0.5em;
  border: thin solid var(--color-hint);
  border-bottom: none;
  ${fancy} &, ${fancy}&: {
    background: gold;
  }
`)

combined

Both style and styled can be used as tagged template functions, so the above can also be written as

header.css.ts:

import {style, styled} from 'qwik-styled-ve'

export const Fancy = style``

// Header: a Qwik Lite Component
export const Header = styled.h1`
  padding: 0.5em;
  border: thin solid var(--color-hint);
  border-bottom: none;
  ${fancy} &, ${fancy}&: {
    background: gold;
  }
`

Only emitting styles you use

By default, the CSS you create will be emitted in a .css file that your html will load.

You can instead get the CSS as a string that you then give to Qwik's useStyles$(). To do this, you must have a default export in your definition:

header.css.ts:

import {styled} from 'qwik-styled-ve'

// This will be replaced with the CSS
export default ''

// Header: a Qwik Lite Component
export const Header = styled.h1`
  padding: 0.5em;
  border: thin solid var(--color-hint);
  border-bottom: none;
`

Header.tsx:

import {component$, useStyles$} from '@builder.io/qwik'
import style, {Header} from './header.css'

export default component$(() => {
  useStyles$(style)

  return <Header>I'm styled!</Header>
})

This has the advantage that your initial HTML includes only the styles you actually use, and they are inline, which reduces lag. If you are building a Single Page Application, this is most likely what you want.

Notes

• All styles you create in a css.ts file are included in the CSS output. They do not get tree-shaken, unlike the exported identifiers. This is vanilla-extract behavior.
• Qwik doesn't do hot reloading at the moment. It also has problems with changing .css files. You might have to reload the page manually sometimes to get styles to apply.

Migrating from Styled Components

Several features are not supported because they are impossible as 0-runtime, or don't make sense in Qwik.

Replacing function interpolation

Instead of embedding a function in your CSS like `color: ${p => p.error ? 'red':'black'}`, you should use extra classes, inline styles, CSS variables, or a combination thereof. Any option is easy to implement with Qwik.

import {Text, showError} from './component.css'

// ... hasError is a boolean
// Object of classnames and booleans
<Text class={{[showError]: hasError}}>text</Text>
// Class string
<Text class={hasError && showError}>text</Text>
// Style object
<Text style={{color: hasError ? 'red' : 'black'}}>text</Text>
// CSS variable that you use in your CSS
<Text style={{"--color-hint": hasError ? 'red' : 'black'}}>text</Text>

Replacing themes

Use CSS variables instead. They are supported in all relevant browsers.

You can also import any code you like to create the CSS at build time, there are no restrictions, go wild!

Vanilla-extract also has nice helper projects for this purpose, Sprinkles and Recipes.

Extending a component

A QwikStyledComponent can be passed to style and styled to Instead of using an existing component to build on, compose the styles that vanilla-extract generates:

import {styled, css} from 'qwik-styled-ve'

const Button = styled.button`
  text-size: 3em;
`

export const RedButton = styled.button([
  Button,
  css`
    background-color: red;
  `,
])

Use as another tag, extending another component, adding props

Things like const Foo = styled(Bar).as('ul').props(...) make the API more complex and are not (yet) supported.

This library aims to stay lean, but if DX can be improved new features will be considered.