Utils properties

Utilities properties are an useful tool if you like to create your own abstractions on top of CSS.

There might be some patterns that ends up coming up often in your css() blocks.

Utilities properties are built to facilitate reusing such declarations anywhere in any component styling declaration.

They live under the reserved utils key from your tokens.config file.

import type { PropertyValue } from 'pinceau'
export default defineTheme({
  space: {
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    4: '1rem'
  },
  utils: {
    px: (value: PropertyValue<'padding'>) => ({ 
      paddingLeft: value,
      paddingRight: value 
    }),
    mx: (value: PropertyValue<'margin'>) => ({ 
      marginLeft: value,
      marginRight: value 
    })
  }
})

import { PinceauTheme, PropertyValue } from 'pinceau'
export const px = (value: PropertyValue<'padding'>) => ({
  paddingLeft: value,
  paddingRight: value,
})
export const mx = (value: PropertyValue<'margin'>) => ({
  marginLeft: value,
  marginRight: value,
})
export const utils = { px, mx } as const
export type GeneratedPinceauUtils = typeof utils
export default utils

<style lang="ts">
css({
  '.my-element': {
    // Will autocomplete with the type of `value` argument of `utils.px`
    px: '{space.4}',
    // Will autocomplete with the type of `value` argument of `utils.mx`
    mx: '{space.2}',
  }
})
</style>

Some limitations of Utils properties has to be known:

• The name of the key must be a const {*} = ... compatible name
  Pinceau will give you a gentle hint in the console if you break this rule.
• They support using types and functions that comes from imports made in tokens.config files.
  These imports has to be added to utilsImports key in the options.

Runtime

To work with runtime features (Variants, Computed Styles or the CSS Prop), you will have to import these utils into the plugin.

To avoid shipping the JavaScript of your utils, Pinceau won't include it by default.

That also means you are free to only use these utils in static styling, and never use it at runtime, skipping the bundle size impact.

import { createApp } from 'vue'
import Pinceau from 'pinceau/runtime'
import utils from '#pinceau/utils'
const app = createApp()
app.use(Pinceau, { utils })