docs: how to load CSS

[tresorama]

This issue is considered "close" because is documentation only.
In future this issue could be used as inspiration for the documentation site.

This issue is a primitive documentation, meant to be discovered by a developer that search in the documentation how to load CSS, and if for some reason, the documentation hasn't yet the answer the dev will search through issue in this repo.
This is what i do, so i presume others dev do it as well.

If you have a scenario not covered in the doc site and also not here in comments, you can help the community by creating a comment where you explain what you did.
Let's help each other.

[tresorama]

Which is difference between enqueue_block_assets and enqueue_block_editor_assets php actions ?

From this article

enqueue_block_editor_assets – This can be used to enqueue block scripts and styles in the admin editor only.

enqueue_block_assets – This is used to enqueue block scripts and styles in both the admin editor and frontend of the site.

[tresorama]

How to load custom CSS only when a block is used

https://developer.wordpress.org/themes/basics/including-css-javascript/#including-css-for-block-styles

https://neliosoftware.com/blog/devtips-smart-enqueuing-block-styles-in-fse/

[tresorama]

Load global CSS in block editor iframe and in frontend

If you use theme.json wordpress generates a stylesheet starting from it.
This stylesheet is used by UI controls in the editor (Font Size, Colors, Padding, ...).

If you want to add a custom CSS file that can overrides the CSS generated from theme.json, you can do this:

In frontend use wp_enqueue_style and add dependency of css generated from theme.json, so your will have priority if has same css specificity.
In block editor iframe, use add_editor_style.

Example

CSS

Your css stylesheet does not need special treatments, it works in both contexts(block editor/site editor and frontend).

/* .../wp-content/my-theme/my-custom-css.css */

.text-2xl {
  font-size: 1.5rem !important;
}

@media (max-width: 600px) {
  .mobile\:text-2xl {
    font-size: 1.5rem !important;
  }
}

Load file

/**
 * Load custom global CSS into both block editor "iframe" and frontend
 *
 * @return void
 */
function my_theme_enqueue_custom_global_css_in_blocks() {
  
  // Add custom CSS to frontend.
  wp_enqueue_style(
    'my-custom-css',
    get_template_directory_uri() . '/my-custom-css.css'
    array( 'global-styles' ),// say to wordpress to inject this file after the css file generated from "theme.json"
  );

  // Add custom CSS to block editor "iframe".
  add_editor_style( 'my-custom-css.css' );

}
add_action( 'after_setup_theme', 'my_theme_enqueue_custom_global_css_in_blocks' );

In frontend, you just add your stylesheet after the one generated from theme.json, to be able to overrides without increasing css specificity.

In the block editor/site editor "iframe" you use the function add_editor_style.
The function add_editor_style injects a CSS file in the block editor "iframe" and adds .editor-styles-wrapper scoped selector to every css definition, also in media query definitions.
For example, .text-2xl become .editor-styles-wrapper .text-2xl

Read #48437 and #48454 to understand why these requirements.

Thanks to carolinan that suggested to use add_editor_style in this issue.

[tresorama]

Others

https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/applying-styles-with-stylesheets/