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.

tokens.config.ts
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
                        

                        
 

                        

                          })
                        

                        

                        

                          }
                        

                        

                        

                          })
                        

                        

                      

                    

                    

                      
                      

                        #pinceau/utils
                        

                        

                          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
                        

                        

                      

                    

                    

                      
                      

                        Your Vue component
                        

                        

                          <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 })
                  

                  

                

              

              

                
                

                   Edit this page on GitHub