Repository navigation
Description
What problem does this feature solve?
Feature Request
Problem
The automatic axis name/label overlap avoidance introduced in #21059 is useful, but makes precise manual positioning difficult.
Currently, nameGap is applied before automatic overlap resolution. If the requested position still overlaps axis labels, ECharts moves the axis name to avoid the collision.
As a result, different nameGap values can produce the same final position. Only values beyond the automatically calculated overlap boundary visibly affect the position.
Since that boundary depends on label dimensions, fonts, rotation, and data, application developers cannot reliably determine what offset to use.
Expected Behavior
I would like to keep nameMoveOverlap: true while applying a precise additional offset after automatic overlap resolution.
For example, a new option could be introduced:
yAxis: {
name: 'Axis title',
nameLocation: 'middle',
nameMoveOverlap: true,
nameGap: 10,
nameOffset: 15 // Proposed API
}The proposed nameOffset would shift the axis name by 15px relative to its automatically resolved position.
Current Limitations
nameGapis applied before collision resolution, so small adjustments can be absorbed by the automatic movement.nameMoveOverlap: falserestores manual positioning but disables automatic avoidance.nameTextStyle.textMargininfluences collision spacing but does not guarantee a precise post-layout offset.- The automatically computed overlap displacement is not exposed through a public API.
Proposal
Introduce a post-overlap offset, either as a signed scalar along the axis-name movement direction or as [dx, dy] in pixels.
Alternatively, exposing the final resolved axis-name position or collision displacement through a public API could allow applications to implement custom positioning.
The key requirement is to combine automatic overlap avoidance with predictable manual positioning, without needing to calculate label boundaries ourselves.
Related Issues and Implementation
- Avoid axisLabel and axisName overflowing the viewport by default. And fix the "contain axis name" breaking. #21059 — Automatic axis name/label overlap avoidance
- Is there a way to prevent the axis name from automatically overlapping with its labels? #17902 — Request for access to axis label boundaries
- ECharts v6.1.0,
src/component/axis/AxisBuilder.ts
Thank you for considering this enhancement!
What does the proposed API look like?
Proposed API
I suggest introducing a new nameOffset option that is applied after automatic axis name/label overlap resolution.
For example:
yAxis: {
name: 'Axis Title',
nameLocation: 'middle',
nameMoveOverlap: true,
nameGap: 10,
nameOffset: 15 // Proposed API: additional 15px after auto-layout
}Expected Behavior
The positioning process would be:
Calculate the initial axis name position using
nameGap.Automatically resolve overlaps with axis labels when
nameMoveOverlap: true.Apply
nameOffsetto the resolved position as an additional pixel offset.
The key distinction is:
nameGap: Controls the initial position before overlap resolution.nameOffset: Controls the additional displacement after overlap resolution.
For example, if the automatic overlap resolution places the axis name 60px away from the axis line:
nameOffset | Final distance -- | -- 0 | 60px 10 | 70px 20 | 80px -10 | 50pxThe negative offset intentionally allows users to move the name closer, even if that introduces overlap.
Why This Is Needed
Currently, changing nameGap within the automatically calculated overlap range may have no visible effect.
This makes precise positioning difficult, especially with dynamic data where axis label sizes change and the overlap boundary cannot be known in advance.
Setting nameMoveOverlap: false is not an ideal workaround because it disables automatic collision avoidance entirely.
The proposed nameOffset would allow developers to benefit from automatic layout while retaining predictable, pixel-precise control over the final axis name position.
Alternative API
If more flexibility is desired, nameOffset could also support a two-dimensional offset:
yAxis: {
nameMoveOverlap: true,
nameOffset: [10, -5] // [dx, dy] in pixels
}This would allow precise positioning in both directions without relying on internal collision calculations.
The exact API name and shape are open to discussion. The primary goal is to provide a predictable offset applied after automatic overlap resolution.
Activity
[-][Feature] Support a post-overlap offset for axis names while keeping nameMoveOverlap enabled[/-][+][Feature] Support a post-overlap offset for axis names while keeping nameMoveOverlap enabled[/+]sidshas03 commentedon Nov 11, 2026
Checked on master (34f4d92).
Problem is there. nameGap is applied before the overlap move. AxisBuilder.ts L853 sets the position from nameGap (middle case is L869: pos.y = labelOffset + nameDirection * gap), then resolveAxisNameOverlap runs. moveIfOverlap (L406) shifts the name only when the rects still hit. So any nameGap inside the label box lands at the same spot. Only a gap bigger than the label extent actually moves it. nameTextStyle.textMargin only grows the collision box (labelLayoutHelper.ts L192). It is not a shift after the move, and it cannot pull the name back in.
Before adding nameOffset, two things:
axisCommonTypes.ts L63-L69 already documents nameGap as the offset from axis line + labels when nameMoveOverlap is true, and the pending line is: "should it named as nameOffset or support [offsetX, offsetY]?". Code does not match that comment. The procedure note right under it (L74-L76) says nameGap is applied first on purpose: "if nameGap is applied after the overlap handling, it may still cause overlap and confuse users." So this ask is already an open question in that file. A new option also called nameOffset will clash with that pending line. A negative offset that overlaps again goes against L75-L76.
Avoid axisLabel and axisName overflowing the viewport by default. And fix the "contain axis name" breaking. #21059 is the merged overlap work this issue points at. That PR does not mention Is there a way to prevent the axis name from automatically overlapping with its labels? #17902, and nothing there links to this issue. Is there a way to prevent the axis name from automatically overlapping with its labels? #17902 is still open. It is about the name sitting on the labels, plus this line: "Is there a way to get the size of the label space/boundaries?" The overlap part was fixed in Avoid axisLabel and axisName overflowing the viewport by default. And fix the "contain axis name" breaking. #21059. The boundary read was never added. It is not a request for a post-overlap offset.
If a pixel nudge after the auto move is still needed, settle the pending on nameGap first. Do not add a second option until that comment and the code say the same thing.
MengqiYao0703 commentedon Nov 12, 2026
Thanks for the detailed investigation! I agree that we should clarify the existing
nameGapsemantics before introducing another option.My main concern is not necessarily the API name, but the inability to specify a predictable additional gap relative to the automatically resolved position.
If
nameGapis intended to represent the distance from the axis labels whennameMoveOverlapis enabled, as documented inaxisCommonTypes.ts, then making the implementation consistent with that behavior would also solve my primary use case.I understand the concern about negative offsets potentially reintroducing overlaps. Supporting negative values is not essential to my request.
Ideally, I would like to be able to specify something like
nameGap: 10and have the axis name consistently positioned with an additional 10px of spacing beyond the automatically determined label boundary, regardless of label size or content.I'm happy with either improving the semantics of the existing
nameGapor another approach that preserves automatic overlap avoidance while allowing predictable spacing.Thanks again for looking into this!
sidshas03 commentedon Nov 12, 2026
Happy to take this. Sounds like we're aligned! Since negative offsets are off the table, I'll leave the L75-76 ordering intact the name won't move back into the labels.
I'll put up a PR against master. If resolveAxisNameOverlap turns out to need more than a position tweak I'll flag it here before going deep.
Faseehshahid246517 commentedon Nov 13, 2026
Hi everyone, thanks for raising and discussing this!
I'd love to help contribute this feature. Before jumping into the implementation, I wanted to quickly check in on the proposed API shape:
Would a hybrid type supporting both a scalar (signed pixel offset along the movement direction) and a 2D tuple (
[dx, dy]in pixels) be preferred?sidshas03 commentedon Nov 13, 2026
@Faseehshahid246517
This is already the documented behaviour, no? axisCommonTypes.ts L63–L69 says
nameGapis the gap from the labels whennameMoveOverlapis on. So a new option isn't really needed the code just doesn't follow its own comment yet.Only catch is L74–L76 right below says
nameGapis applied before the overlap move on purpose. So the two comments don't agree. Someone from the team has to pick which one holds. Once that's settled I can raise a PR.Faseehshahid246517 commentedon Nov 13, 2026
Thanks for spotting this, @sidshas03. I agree the two comments in
axisCommonTypes.ts contradict each other, and a maintainer should decide
which one is intended.
I took the behaviour in L74-L76 (nameGap applied before overlap resolution)
as the current contract, since that is how the code behaves today and how
#21834 describes it. Changing nameGap to apply after overlap resolution would
shift existing charts, so this PR adds nameOffset as a new option with a
default of 0 and leaves nameGap unchanged.
If the maintainers decide nameGap should be post-overlap instead, I'm happy
to rework or close this PR. Could someone from the team confirm the intended
semantics?
sidshas03 commentedon Nov 13, 2026
Fair enough, and honestly your reading is the safer one. L74–76 is what the code does today, so taking that as the current contract makes sense for backward compat. Flipping
nameGapto post-overlap, which is what my #21837 does, would shift existing charts, that's exactly the risk you're flagging.So we've basically arrived at the two branches of the same decision. My PR changes
nameGapsemantics; yours addsnameOffsetand leavesnameGapas it is. Both are stuck on the same question: which of the two contradicting comment blocks inaxisCommonTypes.tsthe team actually wants to hold.I'd suggest we don't go deep on either until a maintainer picks one. No sense in two PRs racing when one is going to be closed anyway. Could a maintainer confirm the intended
nameGapbehaviour whennameMoveOverlapis on? Once that's decided it's clear which PR to carry forward, and I'm happy to close mine ifnameOffsetis the direction.Faseehshahid246517 commentedon Nov 13, 2026
Agreed, thanks @sidshas03. Let's hold both until a maintainer confirms the
intended nameGap behaviour when nameMoveOverlap is on.
For whoever picks this up, the two options are:
layouts)
overlap resolution (no change to existing charts)
Either way the contradiction between the two comments in axisCommonTypes.ts
should be fixed so the docs match the chosen behaviour. I'll close mine if the
team prefers the nameGap route.
sidshas03 commentedon Nov 13, 2026
Had a proper look through this. One thing I'm not clear on the offset gets applied inside the
axisNamebuild, but the grid reserves name space fromnameLayout.rectinGrid.ts, and that pass runs earlier. So does a large positivenameOffsetactually get room reserved for it, or does it just spill out of the grid? Yourmain11case (containLabel+ offset 60) is exactly where this would break, if it breaks. Did you step through that one yourself and confirm the name stays inside, or are we going by the tests passing? I'd want the actual logic walked through here, since the whole point of #21059 was to stop the name overflowing. Also one small thing:normalizeNameOffsetcheckslength >= 2but the type is[number, number], so[1, 2, 3]slips through quietly, better to tighten that. Can you take another pass on the overflow case and explain how it holds up?