Why using "css" and not "style" for react components props (and is there a way to change that ?)

[Aarbel]

/** Returns a function that applies styles and variants for a specific class. */
export declare const css: Stitches['css']

Hi Stitches team, why are you using the "css" string to provide css styles to a stitches components, instead of using the string "style" ?

[hennessyevan]

They do different things and both have valid use-cases

When you set css, stitches creates css rules and attaches them to the stitches stylesheet in the head of the document which is more powerful but more expensive for dynamic values.
VS
When you use the style prop, react sets those styles on the element directly. You might want to use this for dynamic style values since it is cheaper than using the css prop in that scenario.

[Aarbel]

Thanks @hennessyevan ! Do you have examples ? i don't really get the difference still.

Most of stitches components receive rules thru component props and not the "css" object, so i don't really get the difference with "style" prop.

---

[hennessyevan]

Sure, there's 3 things at play here in this case. I've not used stitches with tailwind, but usually it goes like this:

Your button:

const Button = styled('button', {
  // ...
  
  variants: {
    tone: {
      filterActive: { },
      brandAccent: { }
    }
  }
})

Variants

This will create a few classes that are put into the head (trivialized here) so that if you switch variants at runtime you're just adding / removing class names which is pretty good for performance.

<style id="stitches">
  .button { ... }
  .button--tone-filterActive { ... }
  .button--tone-brandAccent { ... }
</style>

<button class="button" >...</button>

CSS Prop

But what if you really need a different appearance for coarse pointers for some business case and it's not likely that you'll add this to your component library anytime soon well then we have an escape hatch that still gives you access to the theme tokens and media queries.

<Button
  css={{
    '@media(pointer: coarse)': {
      borderColor: '$brandAccent',
      backgroundColor: 'rgb(40, 250, 110)',
    },
  }}
/>

<style id="stitches">
  .button { ... }
  .button--tone-filterActive { ... }
  .button--tone-brandAccent { ... }
  
  @media(pointer: coarse) {
    .button-xyz {
      border-color: var(--sx-colors-brandAccent);
      background-color: rgb(40, 250, 110)
    }
   }
</style>

<button class="button button-xyz" >...</button>

This is fine for those escape hatches, it's an inversion of control so that you're not stuck maintaining a bunch of <0.1% edge cases. The downside is that the css rule here is created dynamically and then pushed into the style tag so it's not as performant as specifying the variants before-hand.

Style prop

This prop is not part of stitches, it's part of react and the DOM but it still has uses. Let's say you want to have your button move around based on some JS. You can't set variants for every x and y coordinate and if you pass those coordinates into the css prop you'd be recreating a css rule and checking for tokens which would be pretty slow.

function myMovingButton() {
  const { x, y } = useMotion()
  
  return (<Button tone="filterActive" css={{ position: 'absolute' }} style={{ top: y, left: x }} />)
}

That would give you something like

<style id="stitches">
  .button { ... }
  .button--tone-filterActive { ... }
  .button--tone-brandAccent { ... }
  .button-xyz { position: absolute; }
</style>

<button class="button button--tone-filterActive button-xyz" style="top: 10px; left: 314px">...</button>