Styling API proposal

Use Case

we provide default themes for some of the widgets in react-instantsearch like the SearchBox. Those widgets are usable out-of-the-box but a user might want to make some small modifications about it -> ex: an obvious example would be colors.

Currently we provide an overrideTheme function (renamed to mergeClassNames in the styling PR). The goal of this function is to take a map of theme keys associated with class names and add those to the default one. This works but in order to use it, you need to use either a regular css file and provide by hand the map themeKeys/classNames, or css modules (when importing the css file, you’ll got the map).

IMHO, it would be more reactish to have also the possibility to perform those modifications by using inline style (and so plain js object). So that you would be able to write something like this:

const searchBoxStyle = {
   submit: {
     backgroundColor: '#1E9C5E  ',
   },
 };
 return <Wrapper >
     <div className="container">
       <SearchBox theme={extendTheme(SearchBox.defaultTheme, searchBoxStyle)}/>
     </div>
   </Wrapper>;

API Proposal

1. rename mergeClassNames to extendTheme.
2. extendTheme will have those two signatures:
   • extendTheme(theme, {themeKey: className, …});
   • extendTheme(theme, {themeKey: {inlineStyle}, …});
3. Add the complete theme (code + classNames) to our widgets instead of just classNames.
4. Add missing state to every widgets in order to inline style to work.

Missing states

Let’s take the RangeRatings widgets as an example to illustrate. Stars color is changing if the whole line match no item. Currently, we have a theme key ratingLinkDisabled that allows a user to interact with the fact that a line can be disabled. However, if I want to change the color of the star, I don’t have the right key to do it by inline style. My only way would be to use descendants css selector like this:

.ratingLinkDisabled > .ratingIconEmpty:before{
}

If I would to allow inline style here, I would need to add an extra key like ratingIconEmptyDisabledBefore

In a more general way: currently with our theming keys, inline style can’t be used for everything compared to class names: thus we need to provide those missing states

[vvo]

I am good with what you propose yes. We will still have the opportunity to add it if our users feels like this is really necessary and come with good usecases.

[mthuret]

Here’s my attempt to summarize our discussion with @bobylito.

The question asked was: do we really want to have different ways to extend a theme? Several ways will mean more maintenance, more debugging, and it’s not clear for a user what he should do.

Based on that, which way should we keep?

The first function extendTheme(theme, {themeKey: className, ...})(existing today under the overrideTheme name) seems to be the less needed. If a user wants to use css to extend a theme, he can already do so by using regular css.

The second function extendTheme(theme, {themeKey: {inlineStyle}, ...}); which propose to extend a theme with inline style will allow a user to colocate his changes near the component. It also seems easier to use than having css-modules using stylesheet where class names are the theme keys name.

In the end, we would only keep the extendTheme(theme, {themeKey: {inlineStyle}, ...}); way.

@vvo: what’s your opinion on the subject?