Axis Range Ticks

Using axis range labels (ticks).

Introduction

Normal axis ticks have a single value such as 5. Range axis ticks have two, a start and end value such as [5, 10].

They can be used to

Label a numeric range of the axis scale
Define category scale groups
Add CalendarPattern intervals to time scales
Drawn on top of series to annotate data point groups

Styling

Modes

Figure 1.

Range Tick Modes

There are three types of range tick render modes as shown in figure 1. They are all used automatically depending on the scenario and axis data types.

Minimal - Automatic only
Curly
Measure

Range tick values are allowed to overlap. When this occurs, they will stack into multiple levels, so they don't take up the same space. However, the range ticks on the first level use a minimal visualization by default. It is similar to normal axis ticks except two ticks are used to indicate the range start and end. Only the first level can and always does use minimal ticks by default, but curly or measure shapes can be used on the first level also if set explicitly.

The curly visualization is useful when defining groups of items rather than exact measurements. Therefore, the curly shape is selected by default when used with category scales on stack levels 2 and up.

Range ticks on numeric and time scales define an exact start and end value. Therefore, the measure shape is selected by default when used with these scale types.

The property axisTick.rangeMode can be set with auto, curly or measure to override default behavior.

Label placement

Curly and measure modes can render a label within the range shape or on top. Labels will go on top if the inside space is not sufficient. This can also be controlled by setting axisTick.label.placement:'outside' explicitly.

Figure 2.

Range Tick Label Placement

Data Types and Range Ticks

Range ticks can have some differing behaviors, features, and appearance depending on the axis data type. In this section we will cover some data type nuances and features to explore the full power of range ticks.

Numeric Scales

Numeric scales are simple and don't have any specific range tick behavior reserved only for numeric scales.

Category Scales

Category scales have qualitative string values such as [apples, oranges, bananas]. The value 'apples' does not refer to a specific point on the scale but rather a section of the scale where all apple data points are grouped. Therefore, string category values are always range values. Internally, categories do translate to numeric values where the center of each category refers to the index in category list array. The numeric range of the category is defined as [index-0.5, index+0.5]. Numeric values can be used with axis ticks on category scales if precision is needed. String values are automatically translated to ranges.

While single value strings are translated to ranges, two string values can be used as well. For example, the range value [apples, oranges] will span both values.

Time Scales

Time scales are fundamentally numeric. The main range tick feature related to time scales is the ability to use calendar pattern values. With this feature, you can easily add range ticks for months, quarters, years or any other interval. One custom tick will generate all the relevant ticks automatically.

The relevant chart configuration options in the example below are:

{
  xAxis: {
    scale_type: "time",
    defaultTick_enabled: false,
    customTicks: [
      {
        // A tick for every month.
        value: {
          month: "*"
        },
        label_text: "%min"
      },
      {
        // Every 3 months
        value: { month: "*", every: 3 },
        label_text: function(d) {
          return "Q" + (Math.floor(new Date(d[0]).getMonth() / 3) + 1);
        }
      },
      {
        // Every year
        value: { year: "*" },
        label_text: "%min"
      }
    ]
  }
}

See the Pen Docs - Time Range Ticks by Arthur Puszynski (@jsblog) on CodePen.

Documentation

Tutorials