RFC: Custom CSS classes

[josefarias]

I've been thinking about which API would enable us to have custom CSS classes for each element while avoiding passing tons of arguments to each instance of combobox_tag. This is a subjective preference of mine. I think having too many args often makes code hard to follow.

I came up with an implementation where you're able to define variants in an initializer and then use them by passing a single param at the call site. Looks like this:

# config/initialiers/hotwire_combobox.rb

HotwireCombobox.setup do |config|
  config.add_variant :filter,
    input: "custom-class another-custom-class",
    handle: "...",
    listbox: "...",
    option: "...",
    selected_option: "...",
    dialog: "...",
    dialog_label: "...",
    dialog_input: "...",
    dialog_listbox: "..."
end

Used like this in a view template:

<%= combobox_tag "filter", @filter_options, variant: :filter %>

We could define the current default classes as a default variant. That means any classes defined in the variant would be used instead of the default classes, not in addition to. Users can include the default classes as part of their custom variants if they wish.

I'm unsure whether we should require every element when defining a variant. Seems fine to leave any omitted elements unstyled as long as we have thorough documentation for which elements we support.

Would love to hear what others think. Particularly @jlw. Also open to other proposals.

[adrienpoly]

I really like the ability to call the combobox_tag with a variant: :filter attribute. this feels very idomatic to me.

For the ability to specify the css classes in an initializer I am not 100% convinced. CSS is a front end job, A front end developper should be able to customise this part. Setting the css classes in the initializer is not something that would be natural for a FE dev and when developping any changes to the configuration will need a sever restart to be visible as initializers are only loaded once at boot. It is probably not something that would need to be changed often but during the development part I can easily assume that several tweeks will be required to achieve a pixel perfect results.

I would like to suggest a slightly different approach

Variant definition

In the initializer we define the the variants, here the filter variant.

# config/initialiers/hotwire_combobox.rb

HotwireCombobox.setup do |config|
  config.variants [:filter]
end

Generated html

The main fieldset would be something like that with the added class

<fieldset class="hw-combobox hw-combobox-filter" data-async-id="state-box" data-controller="hw-combobox" ...>

Variant styling

Then we can style using standard css

  .hw-combobox.hw-combobox-filter {
    /* custom classes */
  }

Searchable classes

When inspecting the html if we see this hw-combobox-filter then it become easy to search it in the code base to find the definition

Generator

To perfect the DX maybe a generator could create a skeleton for the CSS variants. Or this could be written in comment in the initializer file

[adrienpoly]

Of course what I am describing could be achieved with what you are proposing

HotwireCombobox.setup do |config|
  config.add_variant :filter,
    input: "hw-combobox-filter__input",
    .....
end

but I still feel adding a convention would make it more Rails way.

[jlw]

The initializer config is the way to go even though making changes requires a restart since this will be a rare style-guide / UX pattern change. This is the Rails way to configure dependencies and it's always possible that a future version of Rails will auto-reload initializers in development (we've seen similar improvements over the years).

My one suggestion is to nest these configs to allow for future variant definitions that go beyond styling. Something like:

HotwireCombobox.setup do |config|
  config.add_variant :filter,
    css_classes: {
      input: "custom-class another-custom-class",
      ...

I'm working on a couple feature proposals here that could each benefit from a tiny bit of non-CSS customization.

[josefarias]

Thanks @adrienpoly @jlw

@adrienpoly,

Setting the css classes in the initializer is not something that would be natural for a FE dev

That's interesting. I'm sure this is the experience for many FE devs but it's not something I would've guessed. Initializers are a basic Rails feature so if it's not something some devs are used to manipulating I think it'd be good to introduce them to it through this gem.

when developping any changes to the configuration will need a sever restart to be visible as initializers are only loaded once at boot.

I hear ya. This would be annoying to deal with. But I think that's on the framework to sort out. I saw Brad's post on X about putting config in controllers instead of initializers. Briefly considered that for this. But I just don't think this is a controller concern — and I don't want this to be the sole gem doing things out of the ordinary in people's projects. Again, would rather not fight the framework on this and wait for Rails to improve the developer experience re: initializers.

Then we can style using standard css

  .hw-combobox.hw-combobox-filter {
    /* custom classes */
  }

This is very similar to what I had originally conceived for the gem. I wrote about it in #22 (comment), which I should've linked for context.

The thing that made me change my mind is @jlw's team's use case where they want to use DaisyUI to style the component. With this approach, they'd have to break down DaisyUI classes into tailwind primitives and apply them with @apply in their CSS. Seems like an unnecessary up-front lift to use the library. I do want to give users a way to inline any classes they like.

@jlw,

My one suggestion is to nest these configs to allow for future variant definitions that go beyond styling [...] I'm working on a couple feature proposals here that could each benefit from a tiny bit of non-CSS customization.

Could you share some more about those proposals? I think the word variant is well understood to relate to presentational concerns. If these features are more functional in nature then I'd be inclined to set them up separately.

It is weird that there's nothing in the API that lets the unfamiliar reader know they're dealing with CSS classes though. Could maybe do

HotwireCombobox.setup do |config|
  config.add_css_variant :filter,
    input: "..."
    # etc

  config.add_css_variant :search,
    input: "..."
    # etc
end

[josefarias]

Well, the passed option wouldn't be :css_variant, but rather just :variant. So maybe no changes are necessary.

I want to wrap up some in-flight things and then cut a new release. I think I'll get to implementing this after that. Thinking we should go with the opening proposal if there's no compelling reason not to by then.

[jlw]

@josefarias - I'm playing around with two changes currently, each of which could benefit from a single config value.

The simple one is adding a clear "X" widget next to the toggle caret, which makes it easier to clear out the field than selecting and deleting the current value. It's possible some people may not want this, so adding a simple flag to skip outputting that element could be nice (I've seen similar options with React combobox libraries).

The more complex change is adding the ability to select multiple values. I've worked with two variants in React apps: render the selected options below/outside the combobox; or render them as pills inside of the combobox (the input field has auto width to take up all free space remaining after the selected options are displayed). I haven't given much though to naming, but was thinking about something like config.add_variant :multiple, { selections_location: :after }.

[josefarias]

Gotcha. I think the X can just be another element that can be hidden or shown with CSS (much like the handle currently is). And multiselect can be an option passed to the combobox: combobox_tag :foo, @options, multiple: true.

EDIT: actually, there may be a11y implications to hiding the X with CSS since it's interactive (unlike the handle which is just for show). Let's cross that bridge when we get there, though.

[josefarias]

As for showing selected options below or outside, I think we should pick one and only support that one in the name of simplicity. We can discuss that in #13.

[adrienpoly]

The thing that made me change my mind is @jlw's team's use case where they want to use DaisyUI to style the component. With this approach, they'd have to break down DaisyUI classes into tailwind primitives and apply them with @apply in their CSS. Seems like an unnecessary up-front lift to use the library. I do want to give users a way to inline any classes they like.

@jlw could you expand on what wasn't working for you.

Here is a test I did to use @apply with DaisyUi classes and it works fine for me

https://play.tailwindcss.com/ILkxtnHOf6?file=css

[adrienpoly]

Can you elaborate on why this would be so bad? Is it the restarting of the server?

"so bad" might be a bit exaggerated, just I don't feel styling should be done in an initializer but rather in a html/css file.

Yeah I think we could

add a data-variant attribute and you could nest all relevant CSS inside a data selector using the default CSS classes. Would that work for you?

yeah that would work, I remember having used a tooltip js lib that would use data-something for variants. Maybe it could be data-combobox-variant="filter" to be a bit more specific.

config.add_variant :filter, **config.variants[:default]

just to be sure to understand this would generate

<fieldset class="hw-combobox" data-variant="filter" ...>

We keep the default hw-combobox and add the data attribute
this way we can inherit what ever style where applied to the base combobox but enhance it with the data selector. 👍

[josefarias]

I don't feel styling should be done in an initializer but rather in a html/css file.

Fair point! Sadly, I don't see a better place to do it specifically for folks who prefer doing their styling with classes only (which, on some projects, that's me!).

As long as we have the data-variant escape hatch for people who prefer styling in CSS files, I think this approach is good for now.

This is what I'm planning on suggesting in the docs (which would match your provided snippet, which is correct):

.hw-combobox[data-variant=filter] {
}

If we recommend this I think we can drop the combobox namespace from the data attr in favor of being concise.

[adrienpoly]

That looks perfect to me 👍

[jlw]

@adrienpoly - this is my first time bringing in Tailwind and Daisy into Rails and with my current config (using the tailwindcss-rails gem) the @apply lines are not being processed. I haven't spent anymore time with this since suggesting CSS class customizations here, and I am assuming there's something wrong on my end.

[adrienpoly]

@jlw I will try it once I get a little time. To see if it is a limitation of tailwind-rails

[adrianthedev]

I hope I'm not too late to chime in.

I do see the simplicity of having the classes in the initializer, but the truth is (IMHO) that simplicity is not always best and I'll try to paint a picture.

I'll preface with the fact that I am a big fan of TailwindCSS and as a big fan I rarely use @apply. I use it only when I can't use the default classes or there's a library involved.
My guess is that I'm not the only one and that are many that prefer it this way.

Another preface, as the maintainer of Avo, as I saw this scenario, is that some folks might not be able to use @apply because of their context. They don't have access to CSS, or they are using it with an older version of Rails that has a weird setup and can't update, or they have weird CSS architectures, etc. I discovered that there are many weird edge cases out there.

Another edge case would be when you have a variant configured, but there's this one unique place where you want one of combobox's elements to look/behave different.

Becuase of these reasons, I would like to propose a different API that can compliment the variants one.

Inline classes.

<%= combobox_tag "filter", @filter_options, variants: [:outline], classes: {
  input: "",
  handle: "",
}
 %>

You, behind the scenes can merge the variants and classes hashes and apply them to the current element.

I can't tell you how many times people thanked me for offering this kind of API where you can configure something ahead of time and enable inline configuration as well.

[josefarias]

You're quite on time @adrianthedev! Thanks for writing this up.

I'm not sure I follow. With the proposed solution (plus the decision to include data-variant), you're able to use tailwind classes without @apply. You're also able to use @apply. You're able to make fine adjustments to variants. And, finally, you're able to style the combobox using plain CSS. And I don't think doing any of that would be particularly cumbersome. Here's how each case might look:

• If you're using tailwind classes only: create a variant in an initializer, use the tailwind classes (and any other CSS classes) to style that named variant.
• If you're using tailwind and would rather use @apply: don't use the initializer and don't import the default styles (or do namespace your component inside a wrapper element), and use the default classes provided by HotwireCombobox to style your component with @apply in your CSS files.
• If you're not using tailwind at all: either use the initializer to style variants with your own CSS classes, or override the default classes provided by HotwireCombobox to style your component in your CSS files, very similar to the previous bullet point.
• If you'd like to make fine one-off adjustments to a single instance of the combobox: you can use a combination of the options above to target your component specifically. Either create a one-off variant that inherits from an existing one (they're all ruby hashes anyway so you can do something like **VARIANT_CONST.merge(...)) or wrap your component in a namespaced element and use CSS with or without @apply to override only the relevant styles.

I think having those options should cover every reasonable situation. The only case for adding classes inline I can think of is one where you don't have access to your initializer. Which, if that's someone's situation, I'd be inclined to say that the gem maybe just isn't for them, unfortunately. I can understand not having much control over your CSS build pipeline. But not having control over your initializer seems like such an edge case that I wouldn't want to compromise on my vision of simplicity to cater to it.

Totally possible I'm missing a reasonable scenario where the current proposal isn't enough. I'll be glad to consider it if that's the case! With what I know now, I think the current proposal is flexible enough.

[josefarias]

I just realized, you could also create a new variant with all the default classes and use data-variant instead of wrapping the combobox for namespacing.

I realize there's tons of options here and that's not necessarily good. Documenting all of them is impractical. I think as long as we give solutions to common setups in the docs we should be good.

[adrianthedev]

My particular suggestion is for the last use-case you pointed out when you want to make fine one-off adjustments to one instance.

If we try to think a bit further down the line, if an app has multiple comboboxes (which I can forsee), then we'll have many one-off variants in the initializer.

These might lead to insecurity with the code.
Nobody will want to change that initializer because they might screw up other styles. It's kind of the composition over inheritance situation.

Also, having to meddle with the initializer to add the one-off adjustments seems a bit in the wrong place to me.

As the author of a library that takes a lot of control over what the user does, I'm thinking about these cases in advance. I think DX is the most important aspect for traction for such a tool.

So yes, it's your vision, and it's definitely up to you to fulfill and ship that vision. I was just adding my two cents into how some users might use it.

[josefarias]

So yes, it's your vision, and it's definitely up to you to fulfill and ship that vision. I was just adding my two cents into how some users might use it.

Your input is super appreciated! Want to be clear I was talking about my vision for general direction but it's our gem. I'm happy to have the vision challenged. This very RFC came from that. But I hope it's understandable that shifting the vision would require some back and forth.

If we try to think a bit further down the line, if an app has multiple comboboxes (which I can forsee), then we'll have many one-off variants in the initializer.

This is making me think we may be providing too many sharp knives. There's too much flexibility in this proposal. You can go variants-only, css-only, css + variants, and picking the right tool for the job is nuanced. I agree many one-off variants is a smell and probably a sign the wrong tool was picked too many times.

Need to take a step back on this and decide whether this should be a library with many sharp knives that lets people get themselves into trouble, or if it should provide a single obvious choice while sacrificing some simplicity at the view layer. Or maybe there's a secret door number three.

[adrianthedev]

Yes. I understand and respect that.

Looking forward to seeing how this library evolves.
I hope it becomes the de-facto combobox library for Rails.

[josefarias]

Per #36 (reply in thread) I'm having thoughts about the current proposal being too flexible.

Here's another idea I'm exploring:

<%= combobox_tag :foo, @options do |combobox| %>
  <% combobox.input_attrs class: "", foobar: "", data: { bar: "" }, aria: { baz: "" } %>
  <% combobox.listbox_attrs class: "",  ... %>
  <% combobox.option_attrs class: "", ... %>
  <% ... %>
<% end %>

All attrs would be merged with the library defaults, with the defaults taking preference. So you wouldn't be able to overwrite anything important.

I've never built such an interface and I don't think I've seen things like it in the wild. Although it's reminiscent of the ViewComponent slots stuff. But I really like that styling can be done in the view (no need for initializers or server restarts) and that you're manipulating each element much more directly — no passing classes at the top level expecting them to be magically propagated. It's also cleaner IMO than passing everything inline as each element is clearly delimited. Finally, you're able to add any atrrs you like to any element in the combobox.

Thoughts are welcome!

[adrianthedev]

Yeah, this could work. It's a bit more verbose but does job (adding classes inline) and even more with adding more attributes.

Good job!

[josefarias]

PR here: #80

Feedback is appreciated. Gonna let it sit for a bit. I'm unsure of the amount of flexibility this introduces. Could be the source of many footguns. Thoughts?

[josefarias]

I think the flexibility might be warranted. People might do funky stuff by listening for the custom events. They might want to make some aria modifications to communicate that.

I'm sure there'll be other useful scenarios with data attrs, too.

And classes, well, we've established that'd be useful, too.

I think I'll just add a note to the docs that we make no promises to provide support for deeply customized instances of the combobox.

[josefarias]

Merged!

[mhenrixon]

Reading this thread and the documentation, I cannot find the best way to make this compatible with daisyui.

I just got started using the gem, but it looks like horseshoes in my daisyui setup. 😂 Should I create variants in the configuration and apply classes to it?

[jlw]

@mhenrixon - I'm running an older copy of the gem from March still so my solution probably won't work exactly for you, but it is possible to get this working with DaisyUI with some tweaks.

Here are the CSS overrides in my app:

.hw-combobox,
.hw-combobox__main__wrapper,
.hw-combobox__input__wrapper {
  width: 100%;
}

.hw-combobox {
  .hw-combobox__main__wrapper {
    &.input {
      border-radius: 0.5rem !important;
      line-height: 2rem;
      padding: 0;
    }

    &.input-error {
      border-color: var(--fallback-er,oklch(var(--er)/var(--tw-border-opacity)));
    }

    &.input-info {
      border-color: var(--fallback-in,oklch(var(--in)/var(--tw-border-opacity)));
    }

    &.input-warning {
      border-color: var(--fallback-wa,oklch(var(--wa)/var(--tw-border-opacity)));
    }
  }

  .hw-combobox__listbox {
    margin-left: -1px;
    width: calc(100% + 2px);
  }

  [role='option'] {
    &:hover,
    &[aria-current='true'] {
      background-color: $color-blue-background-light;
    }

    &[aria-selected='true'] {
      background-color: $color-blue-background-medium;
      color: $color-white;
    }
  }

  .highlight {
    background-color: transparent;
    color: inherit;
    font-weight: bold;
    padding: 0;
  }

  .input {
    .hw-combobox__multiple_selection {
      border-color: var(--in);
    }
  }

  .combobox-input,
  .combobox-input:focus-visible {
    border: none;
    box-shadow: none;
    font-size: inherit;
    line-height: inherit;
  }
}

.hw-combobox--multiple {
  .hw-combobox__inner__wrapper {
    padding: 0 0.25rem;
    margin-right: 1.5rem;
  }
}

and here's what it looks like on the page - the "Referrer" field on the top right is a plain <select> and the two with orange arrows are combo boxes:

I have a bunch of stimulus controllers that need to peek into and trigger actions on these fields, so I wrote my own Phlex component that grabs all of the attributes from the gem's component and then adds in what I need. I don't remember how much I customized that, so here's the HTML that's generated for the second combobox in my screenshot:

[mhenrixon]

That was pretty close to be honest:

So, if I change your CSS and remove the margins on the elements, that's pretty dope.

There are some weird edges that I can likely style away. I would be delighted if @josefarias could share some thoughts on how to best customize the combobox's appearance.

I would love to have the dropdown match the style here as well:

[josefarias]

Hey @mhenrixon, glad to see you're using the combobox.

I think this'd be the most idiomatic way to style with daisyui:

# In a helper...
def daisy_combobox_tag(*args, **kwargs)
  combobox_tag(*args, **kwargs) do |combobox|
    combobox.input_attrs class: "your daisyui classes here"
    combobox.listbox_attrs class: "..."
    combobox.option_attrs class: "..."
    # ...
  end
end

Alternatively, if you're able to use @apply, could do something like this (but I'm not sure whether it works with daisyUI classes):

.hw-combobox__main__wrapper {
  @apply your tailwind classes here;
}
.hw-combobox__handle {
  @apply ...;
}
.hw-combobox__listbox {
  @apply ...;
}
/* ... */

Now, some quirks might come up now that you're overriding the default styles. You have the option not to include them (not recommended), or override them (recommended).

Either way, I suggest you become quite familiar with the styles included by the library (it's just a single CSS file) and make ample use of your browser devtools — that'll be your best bet to fix individual styling issues like the ones pictured above. Those styles could come from anywhere, so I'd need a live example to help debug.

I will say the default css takes care of improving usability for some edge cases. That's why I don't recommend removing it.

EDIT:
You can find a full list of overridable CSS classes in the docs.
Full list of customizable sub-components here:

hotwire_combobox/test/dummy/app/views/comboboxes/custom_attrs.html.erb

Lines 1 to 14 in 6fff047

	<%= combobox_tag "state", State.all, label: "state" do |combobox| %>
	<% combobox.customize_fieldset class: "custom-class--fieldset", data: { customized_fieldset: "" } %>
	<% combobox.customize_label class: "custom-class--label", data: { customized_label: "" } %>
	<% combobox.customize_hidden_field class: "custom-class--hidden_field", data: { customized_hidden_field: "" } %>
	<% combobox.customize_main_wrapper class: "custom-class--main_wrapper", data: { customized_main_wrapper: "" } %>
	<% combobox.customize_input class: "custom-class--input", data: { customized_input: "" } %>
	<% combobox.customize_handle class: "custom-class--handle", data: { customized_handle: "" } %>
	<% combobox.customize_listbox class: "custom-class--listbox", data: { customized_listbox: "" } %>
	<% combobox.customize_dialog class: "custom-class--dialog", data: { customized_dialog: "" } %>
	<% combobox.customize_dialog_wrapper class: "custom-class--dialog_wrapper", data: { customized_dialog_wrapper: "" } %>
	<% combobox.customize_dialog_label class: "custom-class--dialog_label", data: { customized_dialog_label: "" } %>
	<% combobox.customize_dialog_input class: "custom-class--dialog_input", data: { customized_dialog_input: "" } %>
	<% combobox.customize_dialog_listbox class: "custom-class--dialog_listbox", data: { customized_dialog_listbox: "" } %>
	<% end %>

[mhenrixon]

Looks like this would fit right into my formbuilder:

class TailwindFormBuilder < ActionView::Helpers::FormBuilder
  def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
    default_options = { class: "checkbox checkbox-primary", autocomplete: "off" }
    merged_options = combine_options(default_options, options)
    add_error_class(method, merged_options)

    super(method, merged_options, checked_value, unchecked_value) + error_tag(method, merged_options)
  end

  def text_field(method, options = {})
    default_options = { class: "input input-bordered input-primary w-full" }
    merged_options = combine_options(default_options, options)
    add_error_class(method, merged_options)

    super(method, merged_options) + error_tag(method, merged_options)
  end
end

This is the most convenient way I have found to normalize styles somewhat in Ruby on Rails without duplicating everything everywhere.

[mhenrixon]

I went with a slightly different approach.

The thing is, with daisyui the UX is so damn simple.

I decided to piggyback that and came up with: https://mhenrixon.com/articles/taggable-array

I already had a bunch of string array columns and it doesn't seem like this gem is optimal for that specific use case.

I'll likely use combo box for search and collection select etc.