Occlusion-opacity not respected when zoomed out in Mapbox GL JS v3.0.0"
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 12.4k
- Forks
- 2.4k
- PR merge metrics
- No merged PRs in 30d
Description
In Mapbox GL JS v3.0.0, when handling icon and text configuration for fixed racks, the icon-occlusion-opacity and text-occlusion-opacity properties stop being respected when zooming out. This leads to incorrect transparency behavior, where icons and labels appear inconsistently or disappear unexpectedly.
Steps to Reproduce
1. Use the following layer configuration:
{
id: LayerId.PALLET_STICKER,
source: SourceId.PALLET,
type: 'symbol',
paint: {
'symbol-z-offset': ['+', 0.1, ['get', 'maxHeight']],
'text-color': '#000000',
'icon-opacity': 1,
'text-opacity': 1,
'text-occlusion-opacity': 0.0001,
'icon-occlusion-opacity': 0.0001,
'text-halo-color': 'white',
'text-halo-width': 1,
'text-halo-blur': 1,
'text-emissive-strength': 0.1,
},
layout: {
'symbol-avoid-edges': true,
'text-field': ['get', '_label'],
'text-font': ['Open Sans Bold'],
'text-anchor': 'center',
'text-allow-overlap': false,
'text-size': {
type: 'exponential',
base: 2,
stops: [
[10, 10],
[20, 16]
],
},
'text-offset': [0, 0],
'text-pitch-alignment': 'map',
'text-rotation-alignment': 'map',
'text-padding': 0,
'text-line-height': 0.5,
'icon-padding': 0,
'icon-image': ['coalesce', ['get', '_icon'], 'default-icon'],
'icon-size': 1,
'icon-allow-overlap': true,
'icon-anchor': 'center',
'icon-offset': ['case', ['==', ['get', '_icon'], 'icon-close'], [135, 135], [-135, 135]],
'icon-pitch-alignment': 'map',
'icon-rotation-alignment': 'map',
},
}
2.Zoom in and observe that the icons and labels are displayed correctly in fixed racks.
3.Zoom out, and notice that the occlusion-opacity values are no longer respected. Icons and text either become transparent or disappear inconsistently for racks .
on Zoom in it works perfect
Expected Behavior
The icon-occlusion-opacity and text-occlusion-opacity properties should work consistently across all zoom levels, ensuring that symbols behind 3D objects fade correctly at any scale.
Actual Behavior
When zoomed out, the occlusion-opacity stops being respected, causing unexpected transparency issues.
This affects icons and text for fixed racks, leading to UI inconsistencies.


Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the symbol layer configuration in the issue and reproduce the behavior by zooming in and out in Mapbox GL JS v3.0.0. Trace the handling of icon-occlusion-opacity and text-occlusion-opacity across zoom levels; the fix is complete when both properties produce consistent fading for symbols behind 3D objects.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- computer-graphics, web-dev
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100