Text Overlay hooks

Text Overlay lets a customer type onto the product. On the frontend it renders the text with PixiJS into a canvas layered over the preview (or into the 3D scene), and on the server it validates the PNG the browser uploads back.

See the hook reference index for how to register PHP and JavaScript callbacks.

PHP filters

JavaScript actions

JavaScript filters

mkl_pc_text_overlay_max_upload_bytes and mkl_pc_text_overlay_max_image_pixels

Both are safety limits on the PNG the browser generates and posts back with the configuration. The byte cap defaults to 5 MB; the pixel cap defaults to 36,000,000 (roughly 6000 × 6000), which guards against decompression-bomb images rather than large legitimate ones.

Return 0 to disable either check.

// A large-format print product needs more headroom.add_filter( 'mkl_pc_text_overlay_max_upload_bytes', function () {	return 15 * MB_IN_BYTES;} );add_filter( 'mkl_pc_text_overlay_max_image_pixels', function () {	return 80000000;} );

Raise these deliberately. Both caps are checked before the image is decoded, which is what makes them useful — a generous limit costs memory on every upload.

PC.fe.text_overlay.pixi_app_added

Fires once the Pixi application exists and its canvas is in the DOM. This is the hook to use for anything that needs the renderer itself — filters, a custom container, a second text style.

wp.hooks.addAction( 'PC.fe.text_overlay.pixi_app_added', 'my-plugin/to', function ( view ) {	const app = view.Papp;          // the PIXI.Application	const container = view.text_container;	// … add your own display objects …} );

Instances are also collected on PC.fe.text_overlay_viewers, keyed per model, if you need to reach one later.

PC.fe.text_overlay.item.change

Fires whenever the customer edits a text item — on every keystroke, not on blur. The first argument is always null (there is no layer model at that point); the second is the choice model.

wp.hooks.addAction( 'PC.fe.text_overlay.item.change', 'my-plugin/to', function ( _null, model ) {	console.log( 'text is now', model.get( 'text' ) );} );

Debounce anything expensive here. The add-on also fires the core PC.fe.choice.change from the same place.

PC.fe.text_overlay.font_loaded

Fires after a web font has been fetched and registered, with the font name. Useful when you draw your own text with the same font and need to know it is ready.

wp.hooks.addAction( 'PC.fe.text_overlay.font_loaded', 'my-plugin/to', function ( name ) {	redrawMyLabelWith( name );} );

PC.fe.text-overlay.preview.display_mode

Decides where the text preview is drawn. The default is 'viewer-layer' — a canvas layered over the product image. Filter it if your theme positions the preview elsewhere.

wp.hooks.addFilter(	'PC.fe.text-overlay.preview.display_mode',	'my-plugin/to',	function ( mode ) {		return mode;	});

PC.fe.text-overlay.fonts_display_mode

The font picker is a dropdown unless the layer's Font list display setting says otherwise. Return 'dropdown' for the compact trigger, or anything else for the expanded list.

wp.hooks.addFilter(	'PC.fe.text-overlay.fonts_display_mode',	'my-plugin/to',	function ( mode, view ) {		// Always expand when there are only a few fonts.		return view.collection.length < 5 ? 'list' : mode;	});

PC.fe.text-overlay.tooltip.options

Tippy.js options for the colour button's tooltip, applied after the core PC.fe.tooltip.options filter. See Advanced Description for the same pattern.

Core hooks it also fires

PC.fe.choice.change and PC.fe.choices.where — see the Product Configurator JavaScript hooks.