Hooks for Global Styles and Design Tokens, and for the style builder that edits block styles. Global Styles are reusable classes with their own CSS, and Design Tokens are the CSS variables of a design system. Both are GenerateBlocks Pro features. The style builder hooks near the end are in the free plugin and apply to the styles of every block.
Jump to
- Permissions
- Design tokens
- Global CSS output
- Performance and usage
- Style builder (JavaScript)
generateblocks.styles.defaultAtRulesgenerateblocks.styles.selectorShortcutsgenerateblocks.blockStyles.selectorsgenerateblocks.editor.blockCssgenerateblocks.editor.allowCustomAtRulegenerateblocks.editor.allowCustomAdvancedSelectorgenerateblocks.editor.allowDevToolsgenerateblocks.styles.onboardingOptionsgenerateblocks.styles.onboardingStyles
Permissions
Managing Global Styles needs the styles capability, and managing Design Tokens needs the tokens capability as well. A user has to pass both the capability check and the can_manage filter.
generateblocks_manage_classes_capability
GB Pro
The generateblocks_manage_classes_capability filter sets the capability needed to manage Global Styles. Design Tokens use it as their default capability too.
Parameters: $capability (string). Default: manage_options.
add_filter( 'generateblocks_manage_classes_capability', function( $capability ) {
return 'edit_theme_options';
} );Related: generateblocks_can_manage_styles, generateblocks_manage_tokens_capability Guide: Global Styles
generateblocks_can_manage_styles
GB Pro
The generateblocks_can_manage_styles filter adds an extra check to managing Global Styles. A user can manage styles only when they have the capability and this filter returns true.
Parameters: $can_manage (bool). Default: true.
add_filter( 'generateblocks_can_manage_styles', function( $can_manage ) {
return $can_manage && ! defined( 'MY_SITE_LOCK_STYLES' );
} );Related: generateblocks_manage_classes_capability, generateblocks_can_manage_tokens Guide: Global Styles
generateblocks_manage_tokens_capability
GB Pro — since GenerateBlocks Pro 2.8.
The generateblocks_manage_tokens_capability filter sets the capability needed to manage Design Tokens.
Parameters: $capability (string). Default: the Global Styles capability, which is manage_options unless you changed it.
add_filter( 'generateblocks_manage_tokens_capability', function( $capability ) {
return 'manage_options';
} );Related: generateblocks_can_manage_tokens, generateblocks_manage_classes_capability Guide: Design Tokens
generateblocks_can_manage_tokens
GB Pro — since GenerateBlocks Pro 2.8.
The generateblocks_can_manage_tokens filter adds an extra check to managing Design Tokens. A user can manage tokens only when they have the tokens capability, this filter returns true, and they can also manage Global Styles.
Parameters: $can_manage (bool). Default: true.
add_filter( 'generateblocks_can_manage_tokens', function( $can_manage ) {
return $can_manage && current_user_can( 'edit_theme_options' );
} );Related: generateblocks_manage_tokens_capability Guide: Design Tokens
Design tokens
generateblocks_design_token_prefix
GB Pro — since GenerateBlocks Pro 2.8.
The generateblocks_design_token_prefix filter sets the prefix of the CSS variable names GenerateBlocks generates for new Design Tokens. Tokens that already exist keep their names.
Parameters: $prefix (string, without leading dashes). Default: gb. The prefix is lowercased and its leading dashes are removed. A value that isn’t a valid CSS identifier part, or isn’t a string, falls back to the default.
add_filter( 'generateblocks_design_token_prefix', function( $prefix ) {
return 'my-site';
} );Related: generateblocks_should_set_container_width Guide: Design Tokens
Global CSS output
GenerateBlocks Pro prints the CSS of all Global Styles. By default it builds the CSS into a file and loads that file, and it prints the CSS inline when the file doesn’t exist.
generateblocks_global_css
GB Pro
The generateblocks_global_css filter changes the Global Styles CSS, both when it is built into a file and when it is printed inline.
Parameters: $css (string). Default: the CSS of all published Global Styles.
add_filter( 'generateblocks_global_css', function( $css ) {
return $css . '.my-utility{margin-inline:auto;}';
} );Related: generateblocks_global_css_print_method Guide: Global Styles
generateblocks_global_css_print_method
GB Pro
The generateblocks_global_css_print_method filter chooses how the Global Styles CSS is loaded: from a file or inline. It is always inline in the Customizer preview, in post previews and on AMP pages.
Parameters: $method (string: file or inline). Default: file.
add_filter( 'generateblocks_global_css_print_method', function( $method ) {
return 'inline';
} );Related: generateblocks_global_css Guide: Global Styles
generateblocks_global_css_priority
GB Pro
The generateblocks_global_css_priority filter sets the wp_enqueue_scripts priority of the Global Styles CSS. It is lower than the priority of the block CSS so that block styles can override Global Styles.
Parameters: $priority (int). Default: 20.
add_filter( 'generateblocks_global_css_priority', function( $priority ) {
return 15;
} );Related: generateblocks_dynamic_css_priority Guide: Global Styles
Performance and usage
generateblocks_styles_posts_per_page
GB Pro
The generateblocks_styles_posts_per_page filter sets the most Global Styles GenerateBlocks loads when it builds their CSS and lists them.
Parameters: $posts_per_page (int). Default: 5000.
add_filter( 'generateblocks_styles_posts_per_page', function( $posts_per_page ) {
return 10000;
} );Related: generateblocks_styles_batch_size Guide: Global Styles
generateblocks_styles_batch_size
GB Pro
The generateblocks_styles_batch_size filter sets how many Global Styles are loaded in one query. When more than this many are needed, GenerateBlocks loads them in batches.
Parameters: $batch_size (int). Default: 200.
add_filter( 'generateblocks_styles_batch_size', function( $batch_size ) {
return 100;
} );Related: generateblocks_styles_posts_per_page Guide: Global Styles
generateblocks_global_style_usage_handlers
GB Pro
The generateblocks_global_style_usage_handlers filter changes the places where GenerateBlocks looks for the use of a Global Style, which the dashboard shows before you delete or rename a style. The built-in handler, style_usage, searches block attributes.
Parameters: $handlers (array keyed by handler ID, each with method and label), $class_name (string, the style’s class name), $assignable_selectors (array). Default: one handler, style_usage.
A handler’s method must already exist on GenerateBlocks_Pro_Styles_Rest, so this filter is mainly for removing or relabelling handlers.
add_filter( 'generateblocks_global_style_usage_handlers', function( $handlers, $class_name, $assignable_selectors ) {
$handlers['style_usage']['label'] = __( 'Used in content', 'my-plugin' );
return $handlers;
}, 10, 3 );Related: generateblocks_usage_search_post_types, generateblocks_condition_usage_handlers Guide: Global Styles
Style builder (JavaScript)
These are wp.hooks filters. Add them with wp.hooks.addFilter() in a script that loads in the block editor.
generateblocks.styles.defaultAtRules
GB Free — GenerateBlocks Pro also uses it.
The generateblocks.styles.defaultAtRules filter changes the screen sizes (at-rules) that the style builder offers. The IDs it defines are also what generateblocks-pro.deviceVisibilityOptions refers to.
Parameters: atRules (array of objects with id, label, value (the at-rule, or an empty string for all screens), icon (a function that returns an element) and show (bool)). Default: all (All screens), largeWidth (Desktop), mediumLargeWidth (Desktop & tablet), mediumWidth (Tablet), mediumSmallWidth (Tablet & mobile) and smallWidth (Mobile). They use the media queries (min-width:1025px), (min-width:768px), (max-width:1024px) and (min-width:768px), (max-width:1024px) and (max-width:767px).
wp.hooks.addFilter(
'generateblocks.styles.defaultAtRules',
'my-plugin/at-rules',
( atRules ) => atRules.map( ( atRule ) => (
'mediumSmallWidth' === atRule.id ? { ...atRule, show: false } : atRule
) )
);Related: generateblocks_media_query Guide: Style Selectors
generateblocks.styles.selectorShortcuts
GB Free — GenerateBlocks Pro uses it for its own blocks.
The generateblocks.styles.selectorShortcuts filter changes the selector shortcuts in the style builder’s Selectors menu, which are quick choices such as Hover.
Parameters: selectorShortcuts (object of groups, each with an optional label and an items array of { label, value }), context (object with selectedBlock, the selected block object). Default: a default group, and often groups such as interactions, links and pseudoElements. GenerateBlocks Pro replaces the groups for its Form, Tabs and Accordion blocks.
wp.hooks.addFilter(
'generateblocks.styles.selectorShortcuts',
'my-plugin/selector-shortcuts',
( selectorShortcuts, { selectedBlock } ) => {
if ( 'generateblocks/text' !== selectedBlock?.name ) {
return selectorShortcuts;
}
return {
...selectorShortcuts,
default: {
...selectorShortcuts.default,
items: [
...( selectorShortcuts.default?.items || [] ),
{ label: 'Focus ring', value: '&:focus-visible' },
],
},
};
}
);Related: generateblocks.editor.allowCustomAdvancedSelector Guide: Style Selectors
generateblocks.blockStyles.selectors
GB Free — GenerateBlocks Pro adds its blocks.
The generateblocks.blockStyles.selectors filter maps a block name to the short name used in its CSS class, so that the editor can target the block’s styles. The class is .gb-{short name}-{uniqueId}.
Parameters: selectors (object of block name => short name), context (object with blockName and uniqueId). Default: generateblocks/text is text, generateblocks/element is element, generateblocks/loop-item is loop-item, generateblocks/looper is looper, generateblocks/media is media, generateblocks/query is query, generateblocks/query-page-numbers is query-page-numbers and generateblocks/shape is shape.
wp.hooks.addFilter(
'generateblocks.blockStyles.selectors',
'my-plugin/block-selectors',
( selectors ) => ( { ...selectors, 'my-plugin/card': 'card' } )
);Related: generateblocks_dynamic_css_blocks Guide: Style Selectors
generateblocks.editor.blockCss
GB Free — GenerateBlocks Pro uses it for the Navigation block.
The generateblocks.editor.blockCss filter changes the CSS the editor shows for a block, which is the block’s own CSS for the editor canvas.
Parameters: css (string), context (object with clientId and name, the block’s name). Default: the block’s editor CSS.
wp.hooks.addFilter(
'generateblocks.editor.blockCss',
'my-plugin/block-css',
( css, { name } ) => ( 'generateblocks/text' === name ? css + '.gb-text{outline:1px dashed #ccc;}' : css )
);Related: generateblocks_block_css Guide: Style Selectors
generateblocks.editor.allowCustomAtRule
GB Free — GenerateBlocks Pro turns it on.
The generateblocks.editor.allowCustomAtRule filter chooses whether the style builder lets people type their own at-rule, such as a custom media query. It is off in the free plugin and GenerateBlocks Pro returns true.
Parameters: allow (bool), context (object with name, the block’s name). Default: false.
wp.hooks.addFilter(
'generateblocks.editor.allowCustomAtRule',
'my-plugin/allow-custom-at-rule',
( allow, { name } ) => ( 'generateblocks/shape' === name ? false : allow ),
20
);Related: generateblocks.editor.allowCustomAdvancedSelector, generateblocks.editor.allowDevTools Guide: Style Selectors
generateblocks.editor.allowCustomAdvancedSelector
GB Free — GenerateBlocks Pro turns it on.
The generateblocks.editor.allowCustomAdvancedSelector filter chooses whether the style builder lets people type their own advanced selector. It is off in the free plugin and GenerateBlocks Pro returns true.
Parameters: allow (bool), context (object with name, the block’s name). Default: false.
wp.hooks.addFilter(
'generateblocks.editor.allowCustomAdvancedSelector',
'my-plugin/allow-advanced-selector',
( allow, { name } ) => ( 'generateblocks/shape' === name ? false : allow ),
20
);Related: generateblocks.styles.selectorShortcuts Guide: Style Selectors
generateblocks.editor.allowDevTools
GB Free — GenerateBlocks Pro turns it on.
The generateblocks.editor.allowDevTools filter chooses whether the style builder shows its developer tools. It is off in the free plugin and GenerateBlocks Pro returns true.
Parameters: allow (bool), context (object with name, the block’s name). Default: false.
wp.hooks.addFilter(
'generateblocks.editor.allowDevTools',
'my-plugin/allow-dev-tools',
() => false,
20
);Related: Editor Access Guide: Style Selectors
generateblocks.styles.onboardingOptions
GB Pro
The generateblocks.styles.onboardingOptions filter changes the starting choices shown when you create a new Global Style.
Parameters: options (array of { label, description, value }), context (object with selectedBlock). Default: empty-class (Blank style) and clone-class (Clone an existing style). When a block with local styles is selected, copy-local (Copy the local block styles) and move-local (Move the local block styles) are added.
wp.hooks.addFilter(
'generateblocks.styles.onboardingOptions',
'my-plugin/onboarding-options',
( options ) => options.filter( ( option ) => 'move-local' !== option.value )
);Related: generateblocks.styles.onboardingStyles Guide: Global Styles
generateblocks.styles.onboardingStyles
GB Pro
The generateblocks.styles.onboardingStyles filter changes the styles a new Global Style starts with, just before it is saved.
Parameters: styles (object, the style data), context (object with type, the starting choice the person picked, such as empty-class). Default: an empty object for a blank style, or the styles copied from the block or cloned from the chosen style.
wp.hooks.addFilter(
'generateblocks.styles.onboardingStyles',
'my-plugin/onboarding-styles',
( styles, { type } ) => styles
);Related: generateblocks.styles.onboardingOptions Guide: Global Styles