CSS Houdini Tutorial

What is a Houdini?

• Paint API - allows you to extend CSS at the step (meaning the rendering stage) of rendering visual elements (color, background, borders, etc.).
• Layout API - allows you to extend CSS at the step of determining the size, position and alignment of elements.
• Animation API - “extension point” in the step of displaying and animating elements.

• Typed Object Model API
• Custom Properties & Values ​​API
• Font Metrics API
• Worklets

CSS future

Typed Object Model (TOM) API

selectedElement.style.fontSize = newFontSize + 'px' // newFontSize = 20
console.log(selectedElement.style.fontSize) // 20px

{
  value: 20,
  unit: 'px'
}

• computedStyleMap (): for parsing computed (not built-in) styles. This method is called before parsing or using other methods.
• attributeStyleMap: for parsing and modifying inline styles. This is an item property.

//       ( )
selectedElement.computedStyleMap().get('font-size') // { value: 20, unit: 'px' }

//   
selectedElement.attributeStyleMap.set('font-size', CSS.em(2))
selectedElement. attributeStyleMap.set('color', 'blue')

//    
selectedElement.computedStyleMap().get('font-size') // { value: 20, unit: 'px' }

//    
selectedElement.attributeStyleMap.get('font-size') // { value: 2, unit: 'em' }

• clear: removes all inline styles
• delete: deletes a specific CSS property and its value
• has: returns true / false depending on the availability of the specified property
• append: adds an extra value to a property that supports multiple values

Detection

let selectedElement = document.getElementById('example')

if(selectedElement.attributeStyleMap){
  // ...
}

if(selectedElement.computedStyleMap){
  // ...
}

Specification Status

Support

Custom Properties and Values ​​API

CSS.registerProperty({
  name: '--colorPrimary',
  syntax: '<color>',
  inherits: false,
  initialValue: 'blue',
})

• name: name of the custom property
• syntax: instruction for parsing. The predefined values ​​are: <color>, <integer>, <number>, <length>, <percentage>, etc.
• initialValue: default value (before overriding, as well as when errors occur)

.gradient-box {
  background: linear-gradient(45deg, rgba(255, 255, 255, 1) 0% var(--colorPrimary) 60%);
  transition: --colorPrimary 0.5s ease;
  ...
}

.gradient-box:hover {
  --colorPrimary: red;
  ...
}

@property --colorPrimary {
  syntax: '<color>';
  inherits: false;
  initial-value: blue;
}

Example

Detection

if(CSS.registeredProperty) {
  // ...
}

Specification Status

Support

Font Metrics API

Specification Status

Vorkleta

• Paint Worklet - Paint API
• Animation Worklet - Animation API
• Layout Worklet - Layout API

Paint API

1. Write and register a worklet using the registerPaint function
2. Call a worklet in HTML or JS using CSS.paintWorklet.addModule
3. Use the paint () method in CSS along with the name of the vorklet and the arguments passed

registerPaint('paintWorkletExample', class {
  static get inputProperties() { return ['--myVariable']; }
  static get inputArguments() { return ['<color>']; }
  static get contextOptions() { return {alpha: true} }

  paint(ctx, size, properties, args) {
    // ...
  }
})

• inputProperties: An array of custom CSS properties that the worklet is observing. This array represents the dependencies of the worklet.
• inputArguments: an array of arguments that can be passed from a function to external CSS
• contextOptions: color transparency. If false, all colors will be completely opaque
• paint: the main function taking the following arguments:
  
  
  • ctx: a 2D drawing context that is almost identical to the 2D canvas context of the Canvas API
  • size: an object with the width and height of the element. Values ​​depend on the layout rendering process. Canvas size is same as actual item size
  • properties: variables contained in inputProperties
  • args: an array of arguments passed to the paint function

CSS.paintWorklet.addModule('path/to/worklet/file.js')

CSS.paintWorklet.addModule('https://url/to/worklet/file.js')

.example-element {
  // paintWorkletExample -  
  // blue - ,  
  background: paint(paintWorkletExample, blue);
}

Example

Detection

if(‘paintWorklet’ in CSS){
  // …
}

@supports(background: paint(paintWorkletExample)){
  // …
}

Specification Status

Support

Animation API

registerAnimation(‘animationWorkletExample’, class {
  constructor(options){
    // …
  }
  animate(currentTime, effect){
    // …
  }
})

• constructor: called when a new instance is created. Used for general setup.
• animate: The main function containing the animation logic. The following parameters are accepted:
  
  
  • currentTime: timestamps on a specific timeline
  • effect: an array of effects used in the animation

//   
await CSS.animationWorklet.addModule(‘path/to/worklet/file.js’)

//    
const elementExample = document.getElementById(‘element-example’)

//  
const effectExample = new KeyframeEffect(
  elementExample, //  
  [ // … ], //  
  { // … } //  - , ,    ..
)

//        
new WorkletAnimation(
  ‘animationWorkletExample’ //  
  effectExample, //  
  document.timeline, //  
  {},  //   
).play()

Time stamps

animate(currentTime, effect){
  effect.localTime = 3000 // 1000ms  + 2000ms  
}

animate(currentTime, effect){
  effect.localTime = currentTime // y = x  
}

const scrollTimelineExample = new ScrollTimeline({
  scrollSource: scrollElement, // ,     
  orientation: ‘vertical’, //  
  startScrollOffset: ‘200px’, //  
  endScrollOffset: ‘800px’, //  
  timeRange: 1200, //  
  fill: ‘forwards’ //  
})

Example

Detection

if(CSS.animationWorklet){
  // …
}

Specification Status

Support

Layout API

registerLayout(‘exampleLayout’, class{
  static get inputProperties() { return [‘--example-variable’] }

  static get childrenInputProperties() { return [‘--exampleChildVariable’] }

  static get layoutOptions(){
    return {
      childDisplay: ‘normal’,
      sizing: ‘block-like’
    }
  }

  intrinsicSizes(children, edges, styleMap){
    // …
  }

  layout(children, edges, constraints, styleMap, breakToken){
    // …
  }
})

• inputProperties: an array of custom CSS properties that are watched by the worklet and that belong to the parent, the element that caused the layout to render. This array represents the layout dependencies
• childrenInputProperties: an array of custom CSS properties that are watched by the widget and which belong to the descendant
• layoutOptions: defines the following layout properties:
  
  
  • childDisplay: The predefined values ​​are block and normal. Defines how the item is displayed (block or line)
  • sizing: The predefined values ​​are block-like and manual. Determines the need for preliminary calculation of element sizes (if not specified)
• intrinsicSizes: defines how the container or its contents are displayed in the layout context:
  
  
  • children: child of the element that caused the page layout to render
  • edges: container borders
  • styleMap: typed container style object model
• layout: the main function for working with the layout:
  
  
  • children: child element
  • edges: borders
  • constraints: constraints imposed by the parent layout
  • styleMap: typed container style object model
  • breakToken: breakpoint for pagination or print layout splitting

CSS.layoutWorklet.addModule(‘path/to/worklet/file.js’)

.example-element {
  display: layout(exampleLayout)
}

How the Layout API works with layout

Example

Detection

if(CSS.layoutWorklet){
  // …
}

Specification Status

Support

Houdini and progressive improvement

Always identify support to avoid errors.

Use Houdini to improve display and visualization.

Use standard CSS as an alternative

Conclusion

References