# Custom CSS for custom appearance

**URL:** <https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838>\
**Category:** Technical Support\
**Tags:** ui-ux\
**Created:** [April 9, 2025, 9:23am UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838 "2025-04-09T09:23:02Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![delcroip](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/delcroip/32/1568_2.png) [@delcroip](https://forum.communityhealthtoolkit.org/u/delcroip)\
**Post date:** [April 9, 2025, 9:23am UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/1 "2025-04-09T09:23:02Z")

</div>

Dear all,

I can add anything on the appearance and it create a custom DOM class “or-appearance-{}” but now I would like to add a CSS to control the UI.

Can I add simply a CSS file that is loaded for forms without changing the docker images ?

Thanks in advance

---

<div class="post-metadata">

**Author:** ![diana](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/diana/32/2049_2.png) [@diana](https://forum.communityhealthtoolkit.org/u/diana)\
**Post date:** [April 9, 2025, 10:29am UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/2 "2025-04-09T10:29:11Z")

</div>

Hi @delcroip

As far as I know. there is no way to inject CSS into webapp, be it a form or just the base page.

---

<div class="post-metadata">

**Author:** ![delcroip](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/delcroip/32/1568_2.png) [@delcroip](https://forum.communityhealthtoolkit.org/u/delcroip)\
**Post date:** [April 9, 2025, 10:35am UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/3 "2025-04-09T10:35:03Z")

</div>

Thanks,

Do you think it could be possible to add something like below (LMM generated) pointing to a custom css folder ?

```js
// Route to dynamically include all CSS files
app.get('/', (req, res) => {
  const cssDir = path.join(__dirname, 'public/custom_css');
  let cssLinks = '';
  
  // Read all files from css directory
  fs.readdir(cssDir, (err, files) => {
    if (err) {
      console.log('Error reading directory:', err);
      return res.send('Error loading CSS files');
    }
    
    // Filter for .css files and create link tags
    cssLinks = files
      .filter(file => file.endsWith('.css'))
      .map(file => `<link rel="stylesheet" href="/css/${file}">`)
      .join('\n');
    
    // Send HTML with all CSS links
    res.send(`
      <!DOCTYPE html>
      <html>
        <head>
          ${cssLinks}
        </head>
        <body>
          <!-- Your content -->
        </body>
      </html>
    `);
  });
});

```

---

<div class="post-metadata">

**Author:** ![jkuester](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/jkuester/32/806_2.png) [@jkuester](https://forum.communityhealthtoolkit.org/u/jkuester)\
**Post date:** [April 9, 2025, 1:55pm UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/4 "2025-04-09T13:55:36Z")

</div>

The problem is not so much the technical “how” to allow custom CSS (though it would be a bit more involved then that code since we need to basically rebuild the service worker file to include the new css). The challenge is doing it in a maintainable way.

To have something like this as a first-class CHT feature, I think we would want to have some way to guarantee things would not break when upgrading to a new CHT version (or at least to be able to warn folks when relevant stuff changes). That becomes very difficult when the control surface is just a blank-slate for any stylesheet. I do know that other apps/platforms offer support for custom stylesheets, but I have not looked too closely at what is involved. It would be interesting to investigate and see what kinds of guardrails are in place (e.g. just supporting customizing a certain fix list of things).

* * *

For those wanting to live on the edge, it is technically possible to update the css files for the CHT without rebuilding the Docker image. The `api` container builds the service worker file from the assets that live in the container at `/service/api/build/static/webapp`. Technically I do not think there is any reason you could not volume-map your custom `.css` file into that directory. However, you would also need to update the `/service/api/build/static/webapp/index.html` file to explicitly link to your custom stylesheet (since by default it is only loading `styles.css`). Once that is done, you still have to trigger the api server do re-build the service worker file (since it is not actively watching for changes in that directory). You can do this by restarting the api container or by changing something else in the service worker file that is already tracked by the api server (e.g. make some change to the `branding` doc in the `medic` db).

Of course, I don’t recommend doing any of this in production. Any of this could change without warning in later CHT versions (and even if things don’t change I am not sure what challenges you might face just trying to upgrade and put your custom changes into a new api container…)

---

<div class="post-metadata">

**Author:** ![delcroip](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/delcroip/32/1568_2.png) [@delcroip](https://forum.communityhealthtoolkit.org/u/delcroip)\
**Post date:** [April 9, 2025, 3:08pm UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/5 "2025-04-09T15:08:06Z")

</div>

in our case we just want to have a background color based on the severity so very low risk

and I just see that we can already use the existing CSS to have something similar [cht-core/webapp/src/css/enketo/medic.less at a2682caf70f2bf0a5e2ca870ad7adeb99f2a57df · medic/cht-core · GitHub](https://github.com/medic/cht-core/blob/a2682caf70f2bf0a5e2ca870ad7adeb99f2a57df/webapp/src/css/enketo/medic.less#L364C5-L379C8)

---

<div class="post-metadata">

**Author:** ![delcroip](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/delcroip/32/1568_2.png) [@delcroip](https://forum.communityhealthtoolkit.org/u/delcroip)\
**Post date:** [April 9, 2025, 4:06pm UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/6 "2025-04-09T16:06:01Z")

</div>

to use it should I write ‘summary h1 red’ ?

---

<div class="post-metadata">

**Author:** ![delcroip](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/delcroip/32/1568_2.png) [@delcroip](https://forum.communityhealthtoolkit.org/u/delcroip)\
**Post date:** [April 10, 2025, 7:13am UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/7 "2025-04-10T07:13:27Z")

</div>

I think it would be nice to have those css available outside summary or even hx, would you accept a PR that put those color management outside summary-hx sections ?

br

---

<div class="post-metadata">

**Author:** ![jkuester](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/jkuester/32/806_2.png) [@jkuester](https://forum.communityhealthtoolkit.org/u/jkuester)\
**Post date:** [April 10, 2025, 5:40pm UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/8 "2025-04-10T17:40:15Z")

</div>

Let me try to summarize my understanding of what we are talking about here. 😅 You want to be able to set different _background colors_ for questions in a form. We already have a (poorly documented) feature that lets you set specific background colors for `note`s that are within a `summary` group by setting a header appearance (e.g. `h2`) and a color appearance (e.g. `red`). You are proposing expanding this functionality to allow setting the background color of form questions independently of the other `summary` or header appearances.

Does that sound correct? If so, I have a few followup questions:

1. Do you want to set the background color just for `note` fields or for pretty much any type of form question?
2. Would a fixed list of available colors (like what we have currently) be sufficient for your needs?
3. Am I correct in thinking you just want to set the background color (and not affect any other formatting/text-size)?

In general, I do think this could be a viable feature that would be useful to the broader community!

---

<div class="post-metadata">

**Author:** ![delcroip](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/delcroip/32/1568_2.png) [@delcroip](https://forum.communityhealthtoolkit.org/u/delcroip)\
**Post date:** [April 11, 2025, 6:43am UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/9 "2025-04-11T06:43:20Z")

</div>

exactly

I think having few colors available for question/note would be great and sufficient in most of the cases (background and/or font color)

Adding an empty custom CSS (like an empty custom.less file, that could be replaced) could also be useful for more advanced case (sometime the customers have very specific requests) but it is a nice to have.

br

---

<div class="post-metadata">

**Author:** ![jkuester](https://communityhealthtoolkit.b-cdn.net/user_avatar/forum.communityhealthtoolkit.org/jkuester/32/806_2.png) [@jkuester](https://forum.communityhealthtoolkit.org/u/jkuester)\
**Post date:** [April 11, 2025, 2:36pm UTC](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/10 "2025-04-11T14:36:06Z")

</div>

Issue logged!

> <https://github.com/medic/cht-core/issues/9893>
>
> \*\*Is your feature request related to a problem? Please describe.\*\*
> 
> Originally p…roposed \[on the forum\](https://forum.communityhealthtoolkit.org/t/custom-css-for-custom-appearance/4838/7).
> 
> In our Enekto forms. we already have a (poorly documented) feature that lets you set specific background colors for \`note\`s that are within a \`summary\` group by setting a header \_appearance\_ (e.g. \`h2\`) and a color \_appearance\_ (e.g. \`red\`). This feature is intended to support formatting the "summary" page at the end of the form where the user can review the details of the data they have captured before submitting it. The header appearances affect the size/alignment of the text and the colors allow for setting the background for that header.
> 
> Unfortunately, this functionality is not flexible enough to support all the desired use cases. Specifically, there is no way to set the color without also setting the header and setting the header really only "works" for \`note\` fields. If you set the header appearances on other types of questions, it can cause undesired layout issues. This ticket proposes expanding the color functionality in the css to allow for setting a background color on all types of questions
> 
> \*\*Describe the solution you'd like\*\*
> 
> Enketo already automatically supports setting the values from the \`appearance\` column in the xlsx as classes on the HTML element for that form question. This is how the \[\`summary\` stuff\](https://github.com/medic/cht-core/blob/a2682caf70f2bf0a5e2ca870ad7adeb99f2a57df/webapp/src/css/enketo/medic.less#L306) works currently. We can target these appearance classes in our css and provide styling that can be toggled on by setting the appearance. 
> 
> My proposal is that we add a new set of supported classes directly under \`.enketo\` that will allow for targeting specific background colors for any question:
> 
> \- \`.or-appearance-background-red\`
> \- \`.or-appearance-background-green\`
> \- \`.or-appearance-background-blue\`
> \- \`.or-appearance-background-yellow\`
> \- \`.or-appearance-background-lime\`
> 
> To use these, you would just set something like \`background-blue\` in the \_appearance\_ column in the xlsx form config.  
> 
> For backwards compatibility, we should retain the existing \`.or-appearance-red/blue/...\` classes, but I think they should be considered deprecated in favor of the more general-purpose \`.or-appearance-background-red/blue/...\` classes. We could even add a \[form validation warning\](https://github.com/medic/cht-conf/tree/main/src/lib/validation/form) to cht-conf to prompt app devs to update their form configuration to the new appearances.
> 
> I do not think there is much we can do here in the way of having automated tests for these changes, but we will want to thoroughly manually test these background colors (particularly with the \[enketo\_widgets\_test.xlsx form\](https://github.com/medic/cht-core/blob/master/tests/e2e/default/enketo/forms/enketo\_widgets\_test.xlsx) since that will let us catch any unintended impacts to all the various enketo widgets we support).
> 
> \*\*Describe alternatives you've considered\*\*
> 
> One discussed alternative is to simply allow for injecting a custom stylesheet as part of the branding assets configurable for the CHT. While I think that could be used for to achieve much more dramatic customization, I remain concerned about the long-term maintainability of that approach. At the very least, I would want to have some kind of set list of things that are officially supported for styling in this way. (AKA some kind of theming structure that would allow for deeper configuration of the CHT styles, but could still be guaranteed not to break/change unexpectedly. One big draw-back of that kind of approach is that it is pretty heavy-handed/technical for achieving something simple like coloring form questions. Thinking as an app developer, if I want to set a background color on a form question, it is much more convenient/straightforward to just be able to set an \`appearance\` value right in my form xlsx instead of trying to figure out my own custom css....