Switch to Style Spec compliant `kebab-case`

[niranjan-talkinglands]

Issue: MapLibre React Native does not support standard style JSON keys (e.g., fill-color)

When using MapLibre style JSON in MapLibre React Native, style properties defined in the standard MapLibre/Mapbox Style Spec are not applied.

For example:

"paint": {
  "fill-color": "#FF0000"
}

does not work in React Native, because the app expects:

fillColor: "#FF0000"

This means the mobile SDK requires camelCase (fillColor) instead of the official style JSON kebab-case (fill-color). This breaks compatibility with existing MapLibre style JSON used on web and servers, and forces manual transformation of style properties before rendering layers.

Expected behavior:
React Native should accept standard MapLibre style JSON keys or provide a built-in conversion layer so styles can be reused across Web and RN without modification.

Actual behavior:
Layers render without styles unless JSON keys are rewritten from fill-color → fillColor, fill-opacity → fillOpacity, etc.

Impact:

• Cannot directly use standard MapLibre style JSON on mobile
• Extra work to convert styles manually
• Inconsistency between MapLibre Web and RN developer experience

Request:
Add support for standard MapLibre style JSON properties in RN or provide an official utility to convert style definitions.

[KiwiKilian]

I'm absolutely in favor of moving to spec compliant JSON for better interoperability/synergies within the ecosystem and also noted this in #583 (comment). It might also allow us to use types from the style spec directly.

It's more a matter of when and time to introduce this breaking change.

@tyrauber how do you think we could go forward about this topic? v11 will bring a lot of breaking changes. We could consider adding this one too. But we could also aim for this in v12.

[tyrauber]

Yeah, I 100% agree. The goal should be interoperability across all of MapLibre. We should strive to be fully style spec compliant. Graceful deprecations are better than breaking changes, but if we need to make a choice, I'd rather introduce breaking changes and get full style compatibility, than not.

[krakowski]

@niranjan-talkinglands Thanks for investigating this issue!

Do you happen to have a list of property names which need to be camel-cased? I tried transforming all kebab-cased properties within a style created using Maputnik, but this resulted in a completely black map. Generally speaking, can map styles exported through Maputnik be made compatible with MapLibre React Native?

[krakowski]

Seems I misunderstood the issue. The exported Maputnik style works as is (with kebab-case properties) in my case. I had a transparent background which looked bright on Maputnik but almost completely black in MapLibre React Native and assumed the style wasn't parsed properly.

{
  "id": "background",
  "type": "background",
  "paint": {
    "background-color": "rgba(232, 171, 255, 0.13)"
  }
}

Turns out, the MapView is rendered on top of a black surface which darkened everything.

After changing the background to a solid color, there are no differences in map rendering between Maputnik and MapLibre React Native.

[niranjan-talkinglands]

@krakowski Hi... The main challenge was the styles which should be passed to the style prop of the layer components were not following this spec https://maplibre.org/maplibre-style-spec/. In this the prominent difference was the difference in the keys. There were also instances where the format of the value was different between the style spec and what the components accepts.

For eg:

In my case to solve the issue I have written a mapper for the keys like this

export const pairing: Record<string, keyof (FillLayerStyle & LineLayerStyle & SymbolLayerStyle & CircleLayerStyle)> = {
"fill-color": "fillColor",
"fill-opacity": "fillOpacity",
"line-color": "lineColor",
"line-opacity": "lineOpacity",
"line-width": "lineWidth",
"line-cap": "lineCap",
"line-join": "lineJoin",
"line-miter-limit": "lineMiterLimit",
"line-round-limit": "lineRoundLimit",
"line-dasharray": "lineDasharray",
"visibility": "visibility",
"fill-outline-color": "fillOutlineColor",
"fill-pattern": "fillPattern",
"fill-antialias": "fillAntialias",
"icon-color": "iconColor",
"text-color": "textColor",
"text-halo-color": "textHaloColor",
"text-halo-width": "textHaloWidth",
"icon-halo-color": "iconHaloColor",
"icon-halo-width": "iconHaloWidth",
"text-font": "textFont",
"text-size": "textSize",
"text-field": "textField",
"icon-anchor": "iconAnchor",
"text-anchor": "textAnchor",
"text-overlap": "textAllowOverlap",
"text-max-width": "textMaxWidth",
"icon-keep-upright": "iconKeepUpright",
"symbol-avoid-edges": "symbolAvoidEdges",
"icon-image": "iconImage",
"icon-ignore-placement": "iconIgnorePlacement",
"text-ignore-placement": "textIgnorePlacement",
"text-optional": "textOptional",
"icon-optional": "iconOptional",

"line-gap-width": "lineGapWidth",
"line-offset": "lineOffset",
"line-blur": "lineBlur",
"line-pattern": "linePattern",
"line-translate": "lineTranslate",
"line-translate-anchor": "lineTranslateAnchor",
"line-gradient": "lineGradient",
"line-sort-key": "lineSortKey",

"icon-opacity": "iconOpacity",
"icon-halo-blur": "iconHaloBlur",
"icon-size": "iconSize",
"icon-padding": "iconPadding",
"icon-text-fit": "iconTextFit",
"icon-text-fit-padding": "iconTextFitPadding",
"icon-rotate": "iconRotate",
"icon-rotation-alignment": "iconRotationAlignment",

"text-opacity": "textOpacity",
"text-halo-blur": "textHaloBlur",
"text-offset": "textOffset",
"text-rotation-alignment": "textRotationAlignment",
"text-line-height": "textLineHeight",
"text-letter-spacing": "textLetterSpacing",
"text-padding": "textPadding",
"text-transform": "textTransform",
"text-justify": "textJustify",
"text-radial-offset": "textRadialOffset",
"text-variable-anchor": "textVariableAnchor",
"text-writing-mode": "textWritingMode",

"symbol-placement": "symbolPlacement",
"symbol-spacing": "symbolSpacing",
"symbol-z-order": "symbolZOrder",

"fill-translate": "fillTranslate",
"fill-translate-anchor": "fillTranslateAnchor",
"fill-sort-key": "fillSortKey",

'icon-overlap': "iconAllowOverlap",
'text-allow-overlap': 'textAllowOverlap',
'icon-offset': 'iconOffset',
'text-keep-upright': 'textKeepUpright'

};

and to handle the value differences I did this:

switch (key) {
        case 'text-overlap':
        case 'icon-overlap': {
            const overlapValue = (value === "always" || value === "cooperative")
                ? true
                : (value === "never" ? false : value);
            styleProps[pairedKey] = overlapValue;
            break;
        }
        case 'icon-padding': {
            styleProps[pairedKey] = [value];
            break;
        }
        default: {
            styleProps[pairedKey] = value;
        }
    }
}