classList overrides only sometimes

[kf5v]

I got a confusing case where classList does not override but merge classes when passed from parent to child.

const App: Component = () => {
  return (
    <div>
      <Button classList={{ 'text-color': true }}>
        Test
      </Button>
    </div>
  );
};
const Button: Component<JSX.ButtonHTMLAttributes<HTMLButtonElement>> = (
  props
) => {
  return (
    <button
      classList={{
        'bg-color': true,
      }}
      {...props}
    ></button>
  );
};

That Button gets both classes applied.

<button class="bg-color text-color">Test</button>

Is it something expected and where I can read more on how and why?
I find it useful, but is it reliable?
Is it possible to use it without the parent->child passed props?

For example the following does not work

const borderColor = {
  classList: { 'border-color': true },
};
<Button classList={{ 'text-color': true }} {...borderColor}>
  Test
</Button>

Example playground: https://stackblitz.com/edit/github-te6jt77k?file=src%2FApp.tsx

[tamish-max]

Yes, what you are seeing is expected — but classList is a bit special in Solid, so it helps to treat it differently from normal props.

On a DOM element, classList is a compiler/runtime helper that toggles classes individually. For reusable components, I’d merge the incoming classList explicitly instead of relying on spread order.

import { splitProps, type JSX, type Component } from 'solid-js';

type ButtonProps = JSX.ButtonHTMLAttributes<HTMLButtonElement>;

const Button: Component<ButtonProps> = (rawProps) => {
  const [local, rest] = splitProps(rawProps, ['class', 'classList']);

  return (
    <button
      {...rest}
      class={local.class}
      classList={{
        'bg-color': true,
        ...local.classList
      }}
    />
  );
};

That makes the behavior predictable.

Why your borderColor example feels different: spreading an object into a component call is plain JS prop merging before the child renders, while classList on the final <button> is the Solid-specific part. So I would not depend on “sometimes it merges” semantics across component boundaries — merge it yourself in the child and it becomes reliable.

[harshagarwalnyu]

Both behaviors are expected and intentional — they come from two different merging mechanisms.

Case 1: {...props} spread in the component body → merge

<button classList={{ 'bg-color': true }} {...props}></button>

SolidJS compiles JSX spreads through mergeProps() when the spread source is a component's props object. mergeProps has special handling for class, classList, and style — it merges them rather than overriding. This means both bg-color (from the component) and text-color (from the caller) are applied. This is intentional: it lets component consumers add classes without losing the component's own styles.

You can read more in the SolidJS docs on mergeProps — the key line is: "mergeProps merges potentially reactive objects without losing reactivity, giving special treatment to class, classList, style, and ref."

Case 2: spreading a plain object literal → override (not merge)

const borderColor = { classList: { 'border-color': true } };
<Button classList={{ 'text-color': true }} {...borderColor}>

Here you're spreading a plain non-reactive JS object, not a SolidJS props object. The JSX compiler treats this as a standard JS object spread — classList from borderColor wins (last write wins), so text-color is dropped. mergeProps semantics only apply when SolidJS can detect that the spread is a reactive props/signal object.

Is it reliable? Yes for case 1. The merge behavior on {...props} is stable and documented. It won't change without a major breaking release.

Can you use merge without the parent→child pattern?

Yes — call mergeProps explicitly:

const merged = mergeProps(
  { classList: { 'text-color': true } },
  borderColor
);
<Button {...merged}>

This gives you the same merge semantics anywhere, not just in component bodies.

[mg1986jp]

Yes, this is expected and reliable. Solid's JSX compiler has special handling for classList — when you spread {...props} that contains classList, it merges the objects rather than replacing them. Same thing happens with class, style, and event handlers.

This is documented in the Solid docs under "Spreading" — spread props get merged with existing props, and for certain "mergeable" attributes (class, classList, style, ref), Solid combines them instead of overriding.

So in your Button example:

<button classList={{ 'bg-color': true }} {...props}>

The compiler generates code that merges the component's own classList with whatever classList comes through props. Both end up on the DOM element.

The reason your second example doesn't work:

const borderColor = { classList: { 'border-color': true } };
<Button classList={{ 'text-color': true }} {...borderColor}>

This is applying the spread at the parent level (on <Button>), not inside the component's JSX. At the parent level, {...borderColor} spreads classList: { 'border-color': true } as a prop, and the explicitly written classList={{ 'text-color': true }} comes after it. With Solid's JSX compilation, the last prop wins at the same level — so borderColor's classList gets overridden by the explicit one.

If you flip the order it'd work:

<Button {...borderColor} classList={{ 'text-color': true }}>

But even then, the merging only happens inside the component where {...props} meets the component's own classList. At the call site, it's just standard prop precedence (last wins).

[chrisjcthomas]

This behavior is expected and is due to the difference between how SolidJS handles props on custom components vs. native HTML/DOM elements:

1. DOM Elements (<button>):
   classList is a compile-time helper in Solid. When you write <button classList={{ 'bg-color': true }} {...props}></button>, the compiler compiles the spread {...props} to dynamically merge attributes at runtime. Solid's runtime helper (spread / classList handler) knows how to merge the static classList with any incoming classList or class props.

2. Custom Components (<Button>):
   When you do <Button classList={{ 'text-color': true }} {...borderColor}>, <Button> is a custom component, so it receives a plain JavaScript props object. Here, standard JavaScript object spread rules apply:
   { classList: { 'text-color': true }, ...borderColor }
   Because borderColor contains classList, the spread key classList will completely overwrite the earlier key in standard JS, rather than merging them.

If you need to merge dynamic classes from a parent into a child component, the standard best practice is to pass them via the class prop and merge them using standard string/template literal interpolation inside the child component:

const Button: Component<JSX.ButtonHTMLAttributes<HTMLButtonElement>> = (props) => {
  return (
    <button
      class={`bg-color ${props.class ?? ''}`}
      {...props}
    ></button>
  );
};