镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

[Feature] Support a post-overlap offset for axis names while keeping nameMoveOverlap enabled #21834

Description

@MengqiYao0703

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

  • nameGap is applied before collision resolution, so small adjustments can be absorbed by the automatic movement.
  • nameMoveOverlap: false restores manual positioning but disables automatic avoidance.
  • nameTextStyle.textMargin influences 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

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:

  1. Calculate the initial axis name position using nameGap.

  2. Automatically resolve overlaps with axis labels when nameMoveOverlap: true.

  3. Apply nameOffset to 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 | 50px

The 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

  1. added
    enThis issue is in English
    pendingWe are not sure about whether this is a bug/new feature.
    on Nov 11, 2026
  2. changed the title [-][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[/+] on Nov 11, 2026
  3. sidshas03 commented on Nov 11, 2026

    @sidshas03

    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:

    1. 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.

    2. 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.

  4. MengqiYao0703 commented on Nov 12, 2026

    @MengqiYao0703
    Author

    Thanks for the detailed investigation! I agree that we should clarify the existing nameGap semantics 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 nameGap is intended to represent the distance from the axis labels when nameMoveOverlap is enabled, as documented in axisCommonTypes.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: 10 and 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 nameGap or another approach that preserves automatic overlap avoidance while allowing predictable spacing.

    Thanks again for looking into this!

  5. sidshas03 commented on Nov 12, 2026

    @sidshas03

    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.

  6. Faseehshahid246517 commented on Nov 13, 2026

    @Faseehshahid246517

    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?

    yAxis: {
      nameMoveOverlap: true,
      nameOffset: 15 // or [10, -5]
    }
  7. sidshas03 commented on Nov 13, 2026

    @sidshas03

    @Faseehshahid246517

    This is already the documented behaviour, no? axisCommonTypes.ts L63–L69 says nameGap is the gap from the labels when nameMoveOverlap is 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 nameGap is 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.

  8. Faseehshahid246517 commented on Nov 13, 2026

    @Faseehshahid246517

    @Faseehshahid246517

    This is already the documented behaviour, no? axisCommonTypes.ts L63–L69 says nameGap is the gap from the labels when nameMoveOverlap is 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 nameGap is 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.

    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?

  9. sidshas03 commented on Nov 13, 2026

    @sidshas03

    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 nameGap to 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 nameGap semantics; yours adds nameOffset and leaves nameGap as it is. Both are stuck on the same question: which of the two contradicting comment blocks in axisCommonTypes.ts the 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 nameGap behaviour when nameMoveOverlap is on? Once that's decided it's clear which PR to carry forward, and I'm happy to close mine if nameOffset is the direction.

  10. Faseehshahid246517 commented on Nov 13, 2026

    @Faseehshahid246517

    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:

    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.

  11. sidshas03 commented on Nov 13, 2026

    @sidshas03

    Had a proper look through this. One thing I'm not clear on the offset gets applied inside the axisName build, but the grid reserves name space from nameLayout.rect in Grid.ts, and that pass runs earlier. So does a large positive nameOffset actually get room reserved for it, or does it just spill out of the grid? Your main11 case (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: normalizeNameOffset checks length >= 2 but 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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enThis issue is in Englishnew-featurependingWe are not sure about whether this is a bug/new feature.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions