Global Styles: an input for custom CSS

[critterverse]

This issue stems from the recent FSE call for testing to create a custom 404 page. For my 404 page, I ended up adding several elements via the Customizer (accessible via Appearances > Themes > Customize), such as a site background image. I imagine that most of what I added will eventually be handled by Global Styles but as a designer, there’s always going to be something that could be tweaked a bit further.

There could be input form in the Global Styles panel for custom CSS:

This mockup includes some basic syntax validation, but it can be as little as what is being discussed here, and doesn't necessarily need the row highlight.

Note the details:

• Full height panel
• Fullscreen button to open in a modal
• Ellipsis menu that if need be can contain a link to "read more about CSS"

---

Issue updated Jan 20.

Initial proposal

What if there was an input form in the Global Styles panel for “additional CSS”? I’ve shown it in these comps living alongside Global Styles top-level options for Color, Typography, and Layout (as proposed in #27473, comment) but it could be more subtle.

I expect there might be some passionate arguments on both sides of this issue, and possibly also some important context around the Customizer that I'm missing 😅 Let's discuss!

Tasks

• Add styles.css to theme.json schema - Global Styles: Add a css style to theme.json to allow setting of custom css strings #46255
• Add custom CSS input option to global styles to site editor - Global styles: add custom CSS panel to site editor #46141
• Verify security for full input and display flow of custom CSS strings
• Move custom css to its own inline style generation method and combine with customizer CSS #47396
• Put the "Read more about CSS" link into an ellipsis menu, and allow the CSS panel to flex all the way to the bottom
• Add inline code completion and linting to input box similar to customizer - moved to separate issue
• Look at the possibility of adding a direct link to additional CSS in the site editor menu as classic themes do in the appearance menu - design decision made not to follow this up
• See if there is a way to surface the validation warnings to the user - currently these only show in the console - Add validation message to custom CSS input #47132
• Provide list of blocks that have had custom CSS applied at the block level - moved to separate issue
• Remove duplication of custom CSS in hybrid themes - not being followed up at this stage

[lukecarbis]

I'd second this proposal. Not all third party blocks are supported by global styles, and if they were, there would still be unsupported properties.

My use case right now is overriding the default background colour of a third-party audio player block. There's no way to do this while using a block theme.

[celloexpressions]

Custom CSS definitely needs to continue to function alongside global styles. Style settings should never expose all of the possibilities in CSS as user-facing options. There is a lot of additional background on the benefits of user-edited CSS in the original core ticket and Make/Core posts from WordPress 4.7. #30496 identifies this particular feature as needing parity and outlines three potential approaches to ultimately maintaining compatibility for all current customizer features.

If #30496 moves in the direction of providing a separate implementation of customizer features in the site editor, we should consider the pros and cons of the current interface. Custom CSS is one of the most successful features in the customizer. It offers instant live preview. The preview is fully contextual - the HTML exactly matches the frontend, so the CSS previewing can also reflect the frontend. And users can inspect the preview markup while customizing.

CSS probably wants to be implemented in a very customizer-like way if it is rebuilt in the global styles context. It almost needs to exist alongside a browse mode (#23328), or otherwise lock the editor canvas during CSS editing to provide the best possible frontend parity in markup. The literal iframe of the frontend works well for a live CSS editor.

It would also be great to see further progress on some things that were planned but not yet implemented for the customizer iteration. See https://core.trac.wordpress.org/ticket/38707 for background including design mockups. If CSS gets another redesign, there's certainly room to improve it further.

[lgersman]

For those who can't wait :

At Ionos, we have developed a tiny plugin for the very same reason.

It simply replaces the input field with a tag-like-editor (similar to the @wordpress/components FormTokenField : https://developer.wordpress.org/block-editor/reference-guides/components/form-token-field/) to allow designers to apply a theme specific set of css classes.

Maybe this is solution to adapt for Gutenberg.

The plugin is about to be open sourced at github (https://github.com/IONOS-WordPress) within the next weeks.

The theme provides the set of css classes using a custom @wordpress/hooks filter :

addFilter(
  'gutenberg-customclassname-tag-input-extension-get-configuration',
  'wp-flausen',
  function (configuration, block) {
    return {
      ...configuration,
      items: [
        {
          label: `Funky effect`,
          value: 'theme-custom-effect-funky',
          description: 'Makes the block appear funky.',
        },
        {
          label: `Thick`,
          category: `Text`,
          value: 'theme-custom-text-thick',
          description: 'Makes the block font thick.',
        },
        {
          label: `Thin`,
          category: `Text`,
          value: 'theme-custom-text-thin',
          description: 'Makes the block font thin.',
        },
  ...

and the css classes in the theme's style.css :

...
.theme-custom-text-thick {
  font-weight: bold;
}

.theme-custom-text-thin {
  font-weight: lighter;
}

.theme-custom-spacing-small {
  padding: 1em;
}

.theme-custom-spacing-medium {
  padding: 2em;
}

.theme-custom-spacing-large {
  padding: 3em;
}
...

The applied css classes can be styled by the theme depending on their "category" in the configuration :

.gutenberg-customclassname-tag-input-extension-tag-category__text {
    background-color: #f0f8ff;
    color: #333;
  }

  .gutenberg-customclassname-tag-input-extension-tag-category__spacing {
    background-color: #789899;
    color: #fff;
  }

  .gutenberg-customclassname-tag-input-extension-tag-category__foreground {
    background-color: #69aade;
    color: white;
  }

[aurooba]

I was trying to build a little site for myself with FSE today, and within 5 minutes I needed to make a custom CSS change, and immediately needed this. I think it's seriously problematic this wasn't made a higher priority. What are the next steps for this?

[bgardner]

I love this idea and have already considered creating an issue for it. With customizer inevitably going away, I think this is a huge win for those who need to customize a few things via CSS.

[BinaryMoon]

IMO Custom CSS is essential for WP. There will always be situations that can't be addressed by global styles (plugins, theme styles held in stylesheets etc) and so I look forward to seeing a solution for this. Personally I would be happy for the customizer to be kept, and only show the Additional CSS box. It could even be rebranded as the CSS Customizer and have no panels.

[aurooba]

Another thought: when this becomes part of Global Styles, perhaps CSS classes created here can be accurately reflected in the Editor when people use the Additional classes area on any block. That would really help as well.

[MethylBromide]

Non-developers -- who are in excess of 90% of people managing WordPress websites -- absolutely need some way to enter CSS rules to tweak the appearance of their site. They will not create a child theme; it's beyond them. They shouldn't have to install a special plugin. This is core functionality that's needed in 100% of sites that aren't custom-developed by a developer, which is to say, 99%+ of sites.

[paaljoachim]

I want ahead and added the "Needs Dev" label as I assume this issue is ready for a developer to work on.

[kauaicreative]

@lgersman I like you modification! Looking forward to accessing the src.

Here is another implementation in order to access tailwinds classes, https://wordpress.org/plugins/website-builder/

[lgersman]

@lgersman I like you modification! Looking forward to accessing the src.

@kauaicreative : I've actually already published the source code (2 todays after posting in this issue), but forgot to post it here 😅

react component for rendering the css classes : https://github.com/lgersman/wp-flausen/tree/develop/packages/react-tag-input

WordPress plugin providing the hook : https://github.com/lgersman/wp-flausen/tree/develop/packages/gutenberg-customclassname-tag-input-extension

example WordPress theme implementation : https://github.com/lgersman/wp-flausen/tree/develop/packages/gutenberg-customclassname-tag-input-extension-theme-example

I already extended the prototype to support CSS classes "per block type" (see https://github.com/lgersman/wp-flausen/blob/develop/packages/gutenberg-customclassname-tag-input-extension-theme-example/src/index.js).

If themes could also provide custom css classes via Global Styles (aka theme.json) instead of a JS hook like in the prototype - a designers dream come true. But that's another story.

Both plugin and theme work properly.

They are not published to the WordPress Plugin/Theme Directory. The intention was just spreading ideas and contributing sourcecode :-)

Here is another implementation in order to access tailwinds classes, https://wordpress.org/plugins/website-builder/

[mtias]

@critterverse can we try moving as a separate section below the "blocks" one?

[carolinan]

I wanted to leave a note about what I have tried so far, - and where I got stuck.

To fetch the data from the custom_css post type to display it in the new global styles screen, I first tried using an existing store. This was not possible because the returned result does not contain the post_content for this particular post type (I was not able to figure out why).

Instead, I needed to created a new REST api route and control, and use it to get the output from the PHP function wp_get_custom_css.

I was not able to find a hook that could be used to apply the custom css correctly inside the Site Editor iframe. This preview is needed so that the user can see the styles, and see them change as they are updating the CSS in the input field.

In the test branch, you can see an attempt to filter BlockListBlock in a way similar to how Duotone uses it; this does not error, but the style tag is repeated, so this will not work.

I also tried adding the CSS as an additional style tag to the EditorStyles component, but I found this to be too early, outside editor styles wrapper.

View test branch.
custom_css post type

[mtias]

Also want to reference the work to add custom CSS to other blocks directly, like Group: #25413

We should see that both approaches are aligned in some of the implementation details.

[dan-zakirov]

Also want to reference the work to add custom CSS to other blocks directly, like Group: #25413

We should see that both approaches are aligned in some of the implementation details.

That would be really great. But it is unclear whether work in this direction would be accomplished. Such styles would make it very easy to live

[Julianoe]

I'm not really sure how deleting any option to input custom CSS helps to make an open and usable platform for the web. Even non tech-saavy users need to adjust some little CSS tweak here and there. Small sites users will often not dev a child theme and won't have/want hire a dev to do it. They will ask for small modifications like "could we make this block from my plugin I use for this and that change in that way". Without custom CSS that won't be possible without a plugin... why force them to a third party plugin when this was always inside Wordpress already?
I really don't understand.

I get it: the goal is to make the most things graphical interface, good UI, etc.. But you won't change the fact that the web is built with html and CSS and sometimes, even when a user uses a full graphical interface, they will want, or need to input custom CSS.

I'll add that letting users input their own CSS is also a way into giving them access to more creative freedom and understanding. Removing that possibility by default from them, is making it more difficult for curious people to start to dig into the way a website is built. Which in my opinion is a bad thing. But maybe the path WP want to go is one of enclosing users into being UI users that can't tweak things and start learning. I know that's how I started my career: by inputing some CSS into some field on a site builder.

And I talk about non tech saavy but there is instances where professional also need to make small adjustments or where clients don't want big changes and have limited budget and what not. I'll just install a third party plugin that will possibly change owners in 6 months, or become insecure, or stop following good practices, etc... where I could have just open a "custom CSS" field. I don't get it.
Just an example: imagine I built my whole site with TwentyTwentyTwo, it's simple, it works well. I install the very very very famous Contact Form 7 plugin. The default style is shit. How do I customize it? I can't. Unless I install third party plugin. Unless I spend almost the same time it took me to throw this first version at making a child theme, document it for the client, explain it to him, tell him where this very specific part of the website will be edited in a file on the server instead of being accessible from the interface etc etc etc. All I wanted was input 4 lines of CSS.

[carolinan]

@Julianoe I don't think anyone is saying that the editor does not need a custom CSS field, I think most of us agree with that: It is a matter of it being difficult to build and to create an interface for it that is easy to use.

[annezazu]

@glendaviesnz where are we on this feature in terms of stabilizing and any follow ups to the above feedback? Curious what might be needed and, if it's more feedback, whether a more formal and dedicated call for testing on Make Test would be helpful.

[glendaviesnz]

@annezazu I will try and get to the feedback and provide a summary in the next day or two.

[glendaviesnz]

@Marc-pi, @mjsdiaz, @ndiego, @justintadlock, @bph, @carolinan - thanks for the feedback. I have added some additional tasks to this issue's description, and these are in a rough priority order that I think they should be worked on.

[glendaviesnz]

@annezazu this feature has been moved out of experimental with this change. I will let you know when some more items in the task list have been covered off and more testing is needed.

[glendaviesnz]

There might be a need for a better access to the Custom CSS

@bph there is a suggestion here to move the Custom CSS to the ellipsis menu in global styles, which is different to the approach you were suggesting, so you may want to take a look at that issue and see if we should remove the open task Look at the possibility of adding a direct link to additional CSS in the site editor based on that.

[gyurmey2]

Are there any plans for custom CSS per block in post editor? Something like this?

[aristath]

Are there any plans for custom CSS per block in post editor?

We're already adding per-block custom-CSS in global-styles. It was merged in Gutenberg in #46571

[gyurmey2]

@aristath, Thank you, but I mean custom CSS in the post/page editor (not global styles). What are the plans for that?

[bph]

@gyurmey2 What's being worked on is block level custom CSS. #44412 but that's still to be accessed via the Styles sidebar.

In the post editor, you find the "ADDITIONAL CSS CLASS(ES)" secion in the Advanced Tab, and now you can style the specific class name via the new Custom CSS via the Global Styles space.

[Louis7777]

@aristath, Thank you, but I mean custom CSS in the post/page editor (not global styles). What are the plans for that?

I'm also wondering about any plans for Custom CSS for the entire post/page, but not global i.e. shouldn't be loaded anywhere else.

[gyurmey2]

@gyurmey2 What's being worked on is block level custom CSS. #44412 but that's still to be accessed via the Styles sidebar.

In the post editor, you find the "ADDITIONAL CSS CLASS(ES)" secion in the Advanced Tab, and now you can style the specific class name via the new Custom CSS via the Global Styles space.

@bph Of course, thank you for the tips, but it doesn't solve two basic problems:

1. Ease of code management.
2. Performance, because global styles are loaded on every page, regardless of whether a given class has been used or not.

Anyway, in previous comments @Louis7777 and @Jabe64 presented arguments why it is so important.

The Blocks CSS plugin has over 4,000 active installs, so the demand is certainly there.

#47862

[Mamaduka]

Let's close the main issue and split the remaining tasks into smaller ones. @glendaviesnz, what do you think?

[glendaviesnz]

Closing this issue as the main feature is now in place and I have opened new issues for the remaining enhancements:

• Global Styles Custom CSS: Add inline code completion and linting to input box similar to customizer #47945
• Global Styles Custom CSS: Provide list of blocks that have had custom CSS applied at the block level #47946

@bph in relation to your suggestion "There might be a need for a better access to the Custom CSS", Design made a deliberate decision to not put the Global Styles custom CSS front and centre, so I have not added an enhancement issue for that, but feel free to comment in that existing issue.

@Mamaduka I can't remember what the final decision was on "Remove duplication of custom CSS in hybrid themes" - did we still want to look at merging the two?

[bph]

Thanks for your hard work on this and picking up on my suggestion @glendaviesnz I'll be happy to teach everyone where to find the most requested feature, now that's getting ready for 6.2. just have to travel a bit farther to get to it. 🙂

[Mamaduka]

@glendaviesnz, we're merging Customizer and Global Styles CSS before outputting them. I think we want to leave those in DB as is. Using both options should be a rare case, and we should recommend using the Global Styles.

[carolinan]

Are we still looking to complete the tasks that have not been checked off, (see the list of tasks in the description) or are they not needed anymore?

[dan-zakirov]

Our websites are our creations, and we want them to look better than anything else! Developers, help us achieve the best results by adding a CSS field for every Gutenberg block!

[Louis7777]

Our websites are our creations, and we want them to look better than anything else! Developers, help us achieve the best results by adding a CSS field for every Gutenberg block!

Yes. Even better, add a page/post CSS field to efficiently organize our styles. We can't have them all in a global styles place and it doesn't make sense to load them where they don't get used. Part of making beautiful creations is good organization, working in a modular way and not getting lost in the code.

[glendaviesnz]

Are we still looking to complete the tasks that have not been checked off, (see the list of tasks in the description) or are they not needed anymore?

@carolinan The issues that are being followed up have been moved to separate issues - I have updated the description.