Skip to content

kb(Chart): Add KB for bubble sizing in multiple Charts #3117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 17, 2025
Merged

kb(Chart): Add KB for bubble sizing in multiple Charts #3117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 21 additions & 12 deletions components/chart/types/bubble.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,18 +18,17 @@ A Bubble chart is useful for visualizing different scientific relationships (e.g

@[template](/_contentTemplates/chart/link-to-basics.md#understand-basics-and-databinding-first)

#### To create a bubble chart:
## Creating a Blazor Bubble Chart

1. add a `ChartSeries` to the `ChartSeriesItems` collection
2. set its `Type` property to `ChartSeriesType.Bubble`
3. provide a data collection to its `Data` property, which contains numerical data for the X and Y axes, and for the bubble size
To use a Chart component with Bubble series:

1. Add a `ChartSeries` to the `ChartSeriesItems` collection.
2. Set its `Type` property to `ChartSeriesType.Bubble`.
3. Provide a data collection to its `Data` property, which contains numerical data for the X and Y axes, and for the bubble size.

>caption A bubble chart that shows projected population change on a plot of life expectancy versus fertility rate

````RAZOR
@* Bubble Series *@

<TelerikChart>

<ChartSeriesItems>
Expand Down Expand Up @@ -90,9 +89,22 @@ A Bubble chart is useful for visualizing different scientific relationships (e.g
new ModelData() { LifeExpectancy = 74.3, FertilityRate = 1.85, PopulationChange = 3000000, Country = "Great Britain" }
};
}

````

## Bubble Sizing

The Chart component determines the physical size of each bubble automatically:

* The maximum bubble size is 20% of the smaller Chart dimension (width or height). This ensures that the largest bubbles do not occupy too much space.
* The minimum bubble size is 2% of the smaller Chart dimension, but not less than `10px`. This ensures that even the smallest bubbles are perceivable and accessible. The smallest bubble size also depends on the largest `Size` value in the Chart series.
* All bubble sizes are set proportionately, as long as they comply with the preceding rules.

As a result of the above algorithms:

* Bubble sizing may not be linear if the ratio between the smallest and largest `Size` values is too big. For example, a 10-fold bubble size difference is achievable with a large-enough Chart, but a 100-fold size difference is not supported.
* The Bubble Chart helps users compare bubble sizes in the same Chart instance, rather than between different instances. To compare bubbles from multiple series, define these series in the same Chart instance.

If you need to [improve the bubble size comparability across several Charts](slug:chart-kb-bubble-size), then use a dummy data item with a `Size` value that matches the maximum `Size` value in all Chart instances.

## Bubble Chart Specific Appearance Settings

Expand All @@ -102,10 +114,8 @@ The color of a series is controlled through the `Color` property that can take a

The `ColorField` can change the color of individual items. To use it, pass a valid CSS color to the corresponding field in the model and the chart will use its values instead of the `Color` parameter.


@[template](/_contentTemplates/chart/link-to-basics.md#opacity-area-bubble)


### Negative Values

Negative values are allowed for the X and Y fields, because they are plotted on standard numerical axes.
Expand Down Expand Up @@ -149,12 +159,11 @@ The size field should, generally, have positive values as it correlates to the p
}
````


@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings)

@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings-numerical)


## See Also

* [Live Demo: Bubble Chart](https://demos.telerik.com/blazor-ui/chart/bubble-chart)
* [Live Demo: Bubble Chart](https://demos.telerik.com/blazor-ui/chart/bubble-chart)
* [Configure Relative Bubble Sizes in Multiple Charts](slug:chart-kb-bubble-size)
154 changes: 154 additions & 0 deletions knowledge-base/chart-bubble-size.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
---
title: Set Specific Bubble Sizes
description: Learn how to define bubble sizes in different Charts that users can compare more easily.
type: how-to
page_title: How to Set Specific Bubble Sizes
slug: chart-kb-bubble-size
tags: telerik, blazor, chart, bubble
ticketid: 1693133
res_type: kb
---

## Environment

<table>
<tbody>
<tr>
<td>Product</td>
<td>Chart for Blazor</td>
</tr>
</tbody>
</table>

## Description

This KB answers the following questions:

* How to display smaller bubbles for smaller values in a specific Telerik Blazor Chart instance?
* How to help users compare bubble sizes for different data in different Charts?
* How to display all bubbles with a specific defined `Size` value in certain dimensions?
* How to use fixed bubble sizes instead of relative?

## Solution

The [Bubble Chart sets the minimum and maximum bubble sizes automatically](slug:components/chart/types/bubble#bubble-sizing), depending on the Chart dimensions, and the smallest and largest `Size` values in all series in the Chart instance.

To display comparable bubble sizes in multiple Charts:

1. Use an additional dummy data item with a `Size` value that matches the largest value in all involved Chart instances.
1. Hide the dummy bubble:
* Set the `Min` or `Max` parameter of `<ChartXAxis>` and `<ChartYAxis>`.
* Position the bubble outside the visible Chart area (viewport).

>caption Use comparable bubble sizes in several Charts

````RAZOR
<h3>Hundreds</h3>

<p>An additional bubble with <code>Size</code> <strong>3000</strong> is positioned outside the visible Chart area.</p>

<TelerikChart Width="70vw" Height="35vh">
<ChartSeriesItems>
<ChartSeries Type="ChartSeriesType.Bubble"
Data="@SeriesData1"
XField="@nameof(BubbleModel.X)"
YField="@nameof(BubbleModel.Y)"
SizeField="@nameof(BubbleModel.Size)">
</ChartSeries>
</ChartSeriesItems>
<ChartXAxes>
<ChartXAxis Min="0" />
</ChartXAxes>
<ChartYAxes>
<ChartYAxis Min="0" />
</ChartYAxes>
<ChartTooltip Visible="true" Shared="true">
<Template>
@{ var dataItem = (BubbleModel)context.DataItem; }
@dataItem.Size
</Template>
</ChartTooltip>
</TelerikChart>

<h3>Thousands</h3>

<p>The max <code>Size</code> value is <strong>3000</strong>. This is the max value in all Charts and series, so there is no need for additional hidden bubbles.</p>

<TelerikChart Width="70vw" Height="35vh">
<ChartSeriesItems>
<ChartSeries Type="ChartSeriesType.Bubble"
Data="@SeriesData2"
XField="@nameof(BubbleModel.X)"
YField="@nameof(BubbleModel.Y)"
SizeField="@nameof(BubbleModel.Size)">
</ChartSeries>
</ChartSeriesItems>
<ChartXAxes>
<ChartXAxis Min="0" />
</ChartXAxes>
<ChartYAxes>
<ChartYAxis Min="0" />
</ChartYAxes>
<ChartTooltip Visible="true" Shared="true">
<Template>
@{ var dataItem = (BubbleModel)context.DataItem; }
@dataItem.Size
</Template>
</ChartTooltip>
</TelerikChart>

<h3>All Series in Same Chart</h3>

<p>There is no need for additional hidden bubbles.</p>

<TelerikChart Width="70vw" Height="35vh">
<ChartSeriesItems>
<ChartSeries Type="ChartSeriesType.Bubble"
Data="@SeriesData1.Take(SeriesData1.Count - 1)"
XField="@nameof(BubbleModel.X)"
YField="@nameof(BubbleModel.Y)"
SizeField="@nameof(BubbleModel.Size)">
</ChartSeries>
<ChartSeries Type="ChartSeriesType.Bubble"
Data="@SeriesData2"
XField="@nameof(BubbleModel.X)"
YField="@nameof(BubbleModel.Y)"
SizeField="@nameof(BubbleModel.Size)">
</ChartSeries>
</ChartSeriesItems>
<ChartTooltip Visible="true" Shared="true">
<Template>
@{ var dataItem = (BubbleModel)context.DataItem; }
@dataItem.Size
</Template>
</ChartTooltip>
</TelerikChart>

@code {
private List<BubbleModel> SeriesData1 = new List<BubbleModel>() {
new BubbleModel() { X = 50, Y = 100, Size = 100 },
new BubbleModel() { X = 150, Y = 200, Size = 200 },
new BubbleModel() { X = 250, Y = 300, Size = 300 },

// Size matches the max Size value in SeriesData2
new BubbleModel() { X = -100, Y = -100, Size = 3000 }
};

private List<BubbleModel> SeriesData2 = new List<BubbleModel>() {
new BubbleModel() { X = 100, Y = 50, Size = 1000 },
new BubbleModel() { X = 200, Y = 150, Size = 2000 },
new BubbleModel() { X = 300, Y = 250, Size = 3000 }
};

public class BubbleModel
{
public int X { get; set; }
public int Y { get; set; }
public int Size { get; set; }
}
}
````

## See Also

* [Bubble Chart](slug:components/chart/types/bubble)
Loading