Bullets – amCharts 5 Documentation

This tutorial will look into all aspects of using bullets on series.

Creating a series bullet

Each series has a bullets property, which is a List of functions.

A function is responsible for returning a Bullet object.

Whenever series needs to create a bullet for a specific data item, it will call the function and expect it to return a new bullet, which then be displayed on actual chart.

So, creating a bullet involves pushing a custom function into series' bullets list:

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {});
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {});
});

NOTEBullet function receives a root object instance as a first parameter. Since bullets can be created in a lot of different places (e.g. external legend), make sure that we use the passed in object to avoid any anomalies.

Bullet contents

Naturally, empty bullet is useless because it does not have anything to display, so we need to set its contents.

To do that, Bullet has a setting sprite which can be set to literally any other element: from something as simple as a Circle object to another full fledged chart.

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 4,
      fill: series.get("fill")
    })
  });
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 4,
      fill: series.get("fill")
    })
  });
});

The above will create a bullet with a circle.

Please note that bullets can be complex and will not inherit series colors automatically, hence we need to explicitly set its color to series color.

See the Pen
Smoothed line series by amCharts team (@amcharts)
on CodePen.0

For an example of how to use images as bullets, refer to "Images" tutorial.

Positioning

A Bullet object has two properties that help position them within the parent element/data item: locationX and locationY.

Those accept numeric values from 0 (zero) to 1 (one) indicating relative position within target element, with zero indicating beginning and one the end.

Some series (e.g. line series) do not have any dimension, so location settings will be ignored.

However in those series that do have elements with actual shapes (e.g. column series), location settings are super useful as it gives us flexibility over positioning of a bullet.

Let's put a Label bullet in the middle of a column in a column series:

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    locationX: 0.5,
    locationY: 0.5,
    sprite: am5.Label.new(root, {
      text: "{valueY}",
      centerX: am5.percent(50),
      centerY: am5.percent(50),
      populateText: true
    })
  });
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    locationX: 0.5,
    locationY: 0.5,
    sprite: am5.Label.new(root, {
      text: "{valueY}",
      centerX: am5.percent(50),
      centerY: am5.percent(50),
      populateText: true
    })
  });
});

NOTE Please note the populateText use above. This is needed to force Label to populate data placeholders with actual data.

See the Pen
Line series with bullets by amCharts team (@amcharts)
on CodePen.0

Some series are represented by a single line. For example Chord, Sankey, or MapLineSeries.

In those cases, only locationX or locationY is used. I.e. on a horizontal Sankey diagram, locationX will be used, and locationY will be ignored altogether.

Relation to data

Among other things, series will also pass relevant data item to the bullet.

That's why bullets can use data placeholders to populate text, as well as heat rules.

Data placeholders

Bullets that use Label as their sprite property can have its text populated using curly bracket enclosed data placeholders.

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Label.new(root, {
      text: "{valueY}",
      populateText: true
    })
  });
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Label.new(root, {
      text: "{valueY}",
      populateText: true
    })
  });
});

The above label will be replaced by the actual Y value of the related data item.

For more information on how data placeholders work, refer to "Data placeholders" tutorial.

Heat rules

Bullets can also benefit from heat rules.

For example circle bullet can have its radius assigned dynamically, according to range of values in the series.

For more information and examples, visit "Heat rules: Bullets".

Template fields

Template fields are way to override some settings for a series item, such as a bullet, via data.

It works by specifying templateField setting on an object, which should point to a key in data that holds that element's settings we want to override.

For an in-depth explanation how this works, refer to "Template fields" tutorial.

That said, there are some caveats when using template fields with a bullet.

The main one is that bullets are different from any other series object in that they are not created via template, but rather by custom function as a new element. This means that settings supplied during its creations will take precedence over ones that would be inherited via a template field.

The below code will not function correctly:

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 5,
      // ERROR:
      // "fill" set directly on a new element will take precedence over one pulled in via templateField
      fill: am5.color(0xff0000),
      templateField: "bulletSettings"
    })
  });
});

series.data.setAll([{
  category: "C1",
  value: 100,
  bulletSettings: {
    fill: am5.color(0x00ff00)
  }
}, {
  category: "C2",
  value: 200,
  bulletSettings: {
    fill: am5.color(0x0000ff)
  }
}]);

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 5,
      // ERROR:
      // "fill" set directly on a new element will take precedence over one pulled in via templateField
      fill: am5.color(0xff0000),
      templateField: "bulletSettings"
    })
  });
});

series.data.setAll([{
  category: "C1",
  value: 100,
  bulletSettings: {
    fill: am5.color(0x00ff00)
  }
}, {
  category: "C2",
  value: 200,
  bulletSettings: {
    fill: am5.color(0x0000ff)
  }
}]);

The correct workaround is to use a separate template to set bullet's "default" settings, and pass it in as a third parameter to its new() method.

The following code will function correctly:

let bulletTemplate = am5.Template.new({
  // This will be default fill for bullets that do not have
  // it set via templateField
  fill: am5.color(0xE6E6E6)
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 5,
      templateField: "bulletSettings"
    }, bulletTemplate)
  });
});

series.data.setAll([{
  category: "C1",
  value: 100,
  bulletSettings: {
    fill: am5.color(0x00ff00)
  }
}, {
  category: "C2",
  value: 200,
  bulletSettings: {
    fill: am5.color(0x0000ff)
  }
}]);

var bulletTemplate = am5.Template.new({
  // This will be default fill for bullets that do not have
  // it set via templateField
  fill: am5.color(0xE6E6E6)
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 5,
      templateField: "bulletSettings"
    }, bulletTemplate)
  });
});

series.data.setAll([{
  category: "C1",
  value: 100,
  bulletSettings: {
    fill: am5.color(0x00ff00)
  }
}, {
  category: "C2",
  value: 200,
  bulletSettings: {
    fill: am5.color(0x0000ff)
  }
}]);

See the Pen
Using templateField with bullets by amCharts team (@amcharts)
on CodePen.0

Selectively displaying bullets

The function that returns a bullet, can also return nothing.

If this happens, the bullet is not displayed.

This allows us to include our own logic into bullet function to display bullets only in places where we want them.

The following code will only show bullets if data for the data item contains showBullets: true:

series.bullets.push(function(root, series, dataItem) {
  if (dataItem.dataContext.showBullets == true) {
    return am5.Bullet.new(root, {
      sprite: am5.Circle.new(root, {
        radius: 7,
        fill: series.get("fill")
      })
    });
  }
});

series.bullets.push(function(root, series, dataItem) {
  if (dataItem.dataContext.showBullets == true) {
    return am5.Bullet.new(root, {
      sprite: am5.Circle.new(root, {
        radius: 7,
        fill: series.get("fill")
      })
    });
  }
});

The demo below uses this approach to display a dot and a label on the last data item of the line series:

See the Pen
Using templateField with bullets by amCharts team (@amcharts)
on CodePen.0

Multiple bullets

Series can contain any number of bullets. Each function pushed into bullets will create a separate bullet for each data item.

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    locationX: 0.5,
    locationY: 0.5,
    sprite: am5.Circle.new(root, {
      radius: 15,
      fill: am5.color(0xffffff)
    })
  });
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    locationX: 0.5,
    locationY: 0.5,
    sprite: am5.Label.new(root, {
      text: "{valueY}",
      centerX: am5.percent(50),
      centerY: am5.percent(50),
      populateText: true
    })
  });
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    locationX: 0.5,
    locationY: 0.5,
    sprite: am5.Circle.new(root, {
      radius: 15,
      fill: am5.color(0xffffff)
    })
  });
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    locationX: 0.5,
    locationY: 0.5,
    sprite: am5.Label.new(root, {
      text: "{valueY}",
      centerX: am5.percent(50),
      centerY: am5.percent(50),
      populateText: true
    })
  });
});

See the Pen
Column series with label bullets by amCharts team (@amcharts)
on CodePen.0

Auto-hiding bullets

We can set up series to automatically hide its bullets if there are a lot of data points and bullets would just overcrowd the chart.

For that purpose, XY chart series has a setting minBulletDistance.

It's a numeric value which means this: if the distance between data items in series is less than X pixels, hide all bullets.

This setting is dynamic, and will react to changing conditions. I.e. when chart is zoomed in and distances between data items increase, hidden bullets may reappear.

Bullet masking

Normally, bullets are constrained to the plot area of the chart.

If some bullet or part of it goes outside, it's clipped.

To disable such clipping, set maskBullets to false in your series settings:

let series = chart.series.push(am5xy.ColumnSeries.new(root, { 
  xAxis: xAxis, 
  yAxis: yAxis, 
  valueYField: field, 
  valueXField: "date",
  maskBullets: false
}));

var series = chart.series.push(am5xy.ColumnSeries.new(root, { 
  xAxis: xAxis, 
  yAxis: yAxis, 
  valueYField: field, 
  valueXField: "date",
  maskBullets: false
}));

See the Pen
Column series with multiple bullets by amCharts team (@amcharts)
on CodePen.0

MORE INFOFor more information on how to work around bullet masking and related issues, refer to "Handling bullet masking" tutorial.

Event handlers

Adding events

There is a couple of ways to attach event handlers to bullets:

Creating a standalone template, adding event handlers to it, then using that template to create bullet sprite element.
Attaching events to each sprite element in bullet function.

The following snippet adds a click event to a bullet using template:

let bulletTemplate = am5.Template.new(root, {});

bulletTemplate.events.on("click", function(ev) {
  console.log("Clicked on a bullet!", ev.target);
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 5,
      fill: series.get("fill")
    }, bulletTemplate)
  });
});

var bulletTemplate = am5.Template.new(root, {});

bulletTemplate.events.on("click", function(ev) {
  console.log("Clicked on a bullet!", ev.target);
});

series.bullets.push(function(root) {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 5,
      fill: series.get("fill")
    }, bulletTemplate)
  });
});

And below is the snippet that will achieve the same behavior, albeit by attaching an event to each new bullet being created:

series.bullets.push(function(root) {
  const circle = am5.Circle.new(root, {
    radius: 5,
    fill: series.get("fill")
  });
  circle.events.on("click", function(ev) {
    console.log("Clicked on a bullet!", ev.target);
  });
  return am5.Bullet.new(root, {
    sprite: circle
  });
});

series.bullets.push(function(root) {
  var circle = am5.Circle.new(root, {
    radius: 5,
    fill: series.get("fill")
  });
  circle.events.on("click", function(ev) {
    console.log("Clicked on a bullet!", ev.target);
  });
  return am5.Bullet.new(root, {
    sprite: circle
  });
});