I am writing an extension and I would like to know the best way to implement form elements, etc. in the most concise and future proof way.

My approach until now has been just to copy from another screen that I consider to look fairly nice, but now that we have projects like https://civicrm.org/extensions/shoreditch in the works, I'd like to future proof my work and would love it if we could start to coalesce around a set of fairly high level rules.

I confess that I haven't yet installed https://github.com/civicrm/org.civicrm.shoreditch or https://github.com/civicrm/org.civicrm.styleguide/ which I suspect may well answer this question. If it does, I have another question: is it possible to write an extension that will look good using our pre-shoreditch theme and the shoreditch theme? Or is the pragmatic approach to just try and make things look nice with Shoreditch?

2 Answers 2


This was covered during CiviCon St. Louis. I'll try to sum up.

  • There's no way to write an extension that works with both pre-Shoreditch and post-Shoreditch conventions.
  • However, it will be a fairly common site in Civi for some time to come to have extensions that implement Shoreditch operating inside of pages that don't. Mosaico is a good example of this.
  • Shoreditch is just one implementation of a Civi theme - the future may hold others. However, for practical purposes I think we can assume there aren't any others coming for a while.

So your options are to either a) ignore all this and do things the old way, or b) implement the Shoreditch theme and make it clear that it's a "dependency" in the docs (until we get for-real dependency management for extensions).

  • I'll add to this that the styleguide extension provides a page which displays common elements -- how to mark them up, and how that markup is displayed in the current theme. This extension was primarily developed to facilitate development of shoreditch, so you'll find that the guide for the "crm-*" theme is basically a stub. Jun 21, 2017 at 13:37

So, Shoreditch is a Bootstrap based theme, and as such if you want to use it in your extension, you need to have your extension's markup comply to the Bootstrap markup convention (documented in the Bootstrap site).

Given that that convention is different than the one used by "vanilla" CiviCRM, you can't really have your extension look the same with and without Shoreditch, unless maybe if you plan to use the custom-civicrm.css file.

custom-civicrm.css is a file that Shoreditch provides that, when used as the value for the "Custom CSS url" field in civicrm/admin/setting/url, will attempt to make all the screens using the old convention (including core ones) look as if they were Bootstrap based. In theory then if you used it you could write your extension using the old convention and having it look good both in a non-shoreditch and in the shoreditch theme.

I'd suggest against it though for a couple of reasons:

  1. The file is far from being finalized and the end result might not look as good as one would hope in certain areas
  2. One of the reasons for developing Shoreditch is to push CiviCRM to migrate gradually to Bootstrap, so writing your extension with the old markup convention while still planning to have it work alongside Shoreditch would not align with that goal.

So I'd agree with Jon G that if you want to use Shoreditch, you should then go all the way and write your extension with the Bootstrap markup

There's a big caveat though and a disclaimer I need to give: Shoreditch is still in an alpha stage of (internal) development and as such I would not recommend using it for production, as many things could still be changed in the meantime (style and implementation wise) and break things downstream

Hope this was helpful! Alessandro

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.