Hero: imageContainerRef and imageContainerClassName are applied to different elements

[rfearing]

Description

Hero currently applies imageContainerRef and imageContainerClassName to different DOM elements.
Because of that mismatch, consumers can’t reliably style the same node they receive via ref.

This creates friction for effects that depend on both:

• direct element access via ref (positioning/portals/measurements), and
• predictable class-based styling on that same element.

In my case, I needed to apply a dither/background effect to the image container. Since the class and ref pointed to different elements, I had to use workarounds and override internal Hero class patterns.

Current behavior

• imageContainerRef points to element A
• imageContainerClassName is applied to element B

Expected behavior

• imageContainerRef and imageContainerClassName should target the same element (the actual image container).

Why this matters

• Avoids fragile selectors like div[class*="Hero-imageContainer"]
• Improves composability for advanced styling and layering
• Reduces dependency on internal implementation details/class names
• Makes the API contract intuitive: “container ref” and “container class” should refer to the same node

Reproduction

1. Render Hero with both imageContainerRef and imageContainerClassName.
2. Inspect in React DevTools / DOM.
3. Observe they land on different elements.

Workaround currently required

I had to use a wrapper + internal-class selector override to force transparent background and place a dither portal layer. This is brittle and breaks encapsulation. (Ref PR)

.ditherContainer {
  position: relative;
}

/* stylelint-disable-next-line selector-no-qualifying-type */
.ditherContainer div[class*="Hero-imageContainer"] {
  background: transparent;
}

.ditherPortal {
  position: absolute;
  inset: 0 0 0 50%;
  z-index: -1;
}

Suggested fix

Ensure imageContainerRef and imageContainerClassName are wired to the same underlying image container element.
If there’s a reason they must remain separate, consider introducing explicit props for both nodes (e.g., imageWrapperRef / imageWrapperClassName and imageContainerRef / imageContainerClassName) and document the distinction clearly.