Skip to main content
Version: 4.2

Commons scales options

To change the global scale, Charba is providing the method getScale in the defaults.

With this method you can get all global configuration of Chart.JS for scale (common one, not related to chart type) and you have got all set and get methods to change or retrieve the global configuration items.

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().setStacked(true);

boolean stacked = Defaults.get().getScale().isStacked();

The following are the attributes that you can set:

NameTypeDefaultDescription
alignToPixelsbooleanfalseAlign pixel values to device pixels.
animatebooleantrueIf true, animate scaling the chart from the center.
backgroundColorString - IsColorrgba(255,255,255,0) -         The background color of scale area.
beginAtZerobooleanfalseIf true, scale will include 0 if it is not already included.
boundsBoundsBounds.TICKSDetermines the scale bounds on time axis.
displayboolean - DisplayDisplay.TRUEIf Display.TRUE, the axis is shown.
graceint0Amount of pixels for added room in the scale range above and below data.
graceAsPercentageString"0%"Percentage (string ending with %) for added room in the scale range above and below data.
labelsLabelsempty LabelsThe labels to display.
maxdouble - String - DateSee descriptionUser defined maximum number for the scale, overrides maximum value from data.
As value, you can set a:
- double for linear, logarithmic and radial scales, with Double.MAX_VALUE as default;
- Date for time and time series scales, with null as default;
- String for category scales, with null as default.
mindouble - String - DateSee descriptionUser defined minimum number for the scale, overrides minimum value from data.
As value, you can set a:
- double for linear, logarithmic and radial scales, with Double.MIN_VALUE as default;
- Date for time and time series scales, with null as default;
- String for category scales, with null as default.
offsetbooleanfalseIf true, extra space is added to the both edges and the axis is scaled to fit in the chart area.
positionPositionPosition.TOPPosition of the axis.
reversebooleanfalseReverses order of tick labels.
singleStackedbooleanfalseIf you might want to stack positive and negative values together.
stackStringUndefined.STRINGSets the stack group. Axes at the same position with same stack are stacked.
stackedbooleanfalseIf the axis are stacked.
stackWeightdouble1Sets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group.
startAngledouble0Starting angle to draw arcs for the first item in a data set. In degrees, 0 is at top.
suggestedMaxdouble - String - DateSee descriptionAdjustment used when calculating the maximum data value.
As value, you can set a:
- double for linear, logarithmic and radial scales, with Double.MAX_VALUE as default;
- Date for time and time series scales, with null as default;
- String for category scales, with null as default.
suggestedMindouble - String - DateSee descriptionAdjustment used when calculating the minimum data value.
As value, you can set a:
- double for linear, logarithmic and radial scales, with Double.MIN_VALUE as default;
- Date for time and time series scales, with null as default;
- String for category scales, with null as default.
weightint0The weight used to sort the axis. Higher weights are further away from the chart area.

The Bounds controls the scale boundary strategy (bypassed by min/max time options):

  • Bounds.DATA: make sure data are fully visible, labels outside are removed.
  • Bounds.TICKS: make sure ticks are fully visible, data outside are truncated.

Grid

The grid configuration defines options for the lines that are run perpendicular to the axis.

The grid configuration is nested in the scale configuration as following:

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().getGrid().setCircular(true);

boolean circular = Defaults.get().getScale().getGrid().isCircular();

The following are the attributes that you can set:

NameTypeDefaultDescription
borderColorString - IsColorDefaults.get().getGlobal()
.getBorderColorAsString()
If set, used as the color of the border line.
borderDashint[][]Length and spacing of dashes on grid lines. See MDN.
borderDashOffsetdouble0Offset for line dashes. See MDN.
borderWidthint1If set, used as the width of the border line.
circularbooleanfalseIf true, grid lines are circular (on radar chart only).
colorString - String[] - IsColor - IsColor[]Defaults.get().getGlobal()
.getBorderColorAsString()
The color of the grid lines. If specified as an array, the first color applies to the first grid line, the second to the second grid line and so on.
See default colors.
displaybooleantrueIf false, do not display grid lines for this axis.
drawBorderbooleantrueIf true, draw border at the edge between the axis and the chart area.
drawOnChartAreabooleantrueIf true, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn.
drawTicksbooleantrueIf true, draw lines beside the ticks in the axis area beside the chart.
lineWidthint - int[]1Stroke width of grid lines.
offsetbooleanfalseIf true, grid lines will be shifted to be between labels. This is set to true in the bar chart by default.
tickBorderDashint[]See descriptionLength and spacing of the tick mark line. If not set, defaults to the grid line borderDash value.
tickBorderDashOffsetdouble - double[]See descriptionOffset for the line dash of the tick mark. If unset, defaults to the grid line borderDashOffset value
tickColorString - String[] - IsColor - IsColor[]See descriptionColor of the tick line. If unset, defaults to the grid line color.
tickLengthint10Length in pixels that the grid lines will draw in the axis area.
tickWidthint - int[]See descriptionWidth of the tick mark in pixels. If unset, defaults to the grid line lineWidth.
zint0z-index of gridline layer. Values less than or equals to 0 are drawn under datasets, greater than 0 on top.

Ticks

The tick configuration defines options for the tick marks that are generated by the axis.

The ticks configuration is nested in the scale configuration as following:

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().getTicks().setAutoSkip(false);

boolean autoSkip = Defaults.get().getScale().getTicks().isAutoSkip();

The following are the attributes that you can set:

NameTypeDefaultDescription
alignElementAlignElementAlign.CENTERThe tick alignment along the axis.
autoSkipbooleantrueIf true, automatically calculates how many labels that can be shown and hides labels accordingly. Labels will be rotated up to maxRotation before skipping any. Turn autoSkip off to show all labels no matter what.
autoSkipPaddingint3The padding between the ticks on the horizontal axis when autoSkip is enabled.
backdropColorString - IsColorrgba(255,255,255,0.75) -         Color of label backdrops.
backdropPaddingPadding2 to all dimensionsThe padding of label backdrop.
See padding documentation for more details.
colorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
Color of ticks.
See default colors.
countintUnefinedValues.INTEGERThe number of ticks to generate. If specified, this overrides the automatic generation.
crossAlignCrossAlignCrossAlign.NEARThe tick alignment perpendicular to the axis.
displaybooleantrueIf true, the tick marks are shown.
fontFontDefaults.get().getGlobal()
.getFont()
Font of ticks.
See Font.
includeBoundsbooleantrueIf true, the defined min and max values should be presented as ticks even if they are not "nice".
labelOffsetint0Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis).

Note: This can cause labels at the edges to be cropped by the edge of the canvas.
maxRotationint50The maximum rotation for tick labels when rotating to condense labels.

Note: Rotation doesn't occur until necessary and only applicable to horizontal scales.
maxTicksLimitint11Maximum number of ticks and gridlines to show.
minRotationint0The minimum rotation for tick labels.
mirrorbooleanfalseThe flips tick labels around axis, displaying the labels inside the chart instead of outside.

Note: Only applicable to vertical scales.
numberFormatNumberFormatOptionsThe number format options used by the default label formatter.
See INTL number format documentation.
paddingint0The padding between the tick label and the axis.
precisionint0If defined and stepSize is not specified, the step size will be rounded to this many decimal places.
sampleSizeintUndefined.INTEGERThe number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length.
showLabelBackdropbooleantrueIf true, draw a background behind the tick labels
sourceTickSourceTickSource.AUTOHow ticks are generated on axis time.
stepSizedoubleDouble.MIN_VALUEUser defined fixed step size for the scale.
textStrokeColorString - IsColorHtmlColor.TRANSPARENTThe color of the stroke around the text.
textStrokeWidthint0Stroke width around the text.
zint0z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top.

Major Tick

The major tick configuration enables for the major tick marks that are generated by the axis. A major tick will affect auto-skipping and major will be defined on ticks in the scriptable options context, by ScaleTickItem class and isMajor method.

The major ticks configuration is nested in the ticks configuration as following:

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().getTicks().getMajor().setEnabled(true);

boolean enabled = Defaults.get().getScale().getTicks().getMajor().isEnabled();

The following are the attributes that you can set:

NameTypeDefaultDescription
enabledbooleanfalseIf true, major ticks marks are generated.

Title

The scale title configuration defines options for the title of the scale. Note that this only applies to cartesian axes.

The scale title configuration is nested in the scale configuration as following:

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().getTitle().setColor(HtmlColor.RED);

IsColor color = Defaults.get().getScale().getTitle().getColor();

The following are the attributes that you can set:

NameTypeDefaultDescription
alignScaleTitleAlignScaleLabelAlign.CENTERAlignment of the scale label.
colorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
Color of scale label.
See default colors.
displaybooleanfalseIf true, the scale label is shown.
fontFontDefaults.get().getGlobal()
.getFont()
Font of scale label.
See Font.
paddingPadding4 to all dimensionsThe padding of title. Only top and bottom are implemented.
See padding documentation for more details.

AngleLines

The angle lines options are used to configure angled lines that are radiated from the center of the chart to the point labels.

The angle lines configuration is nested in the scale configuration as following:

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().getAngleLines().setLineWidth(2);

int lineWidth = Defaults.get().getScale().getAngleLines().getLineWidth();

The following are the attributes that you can set:

NameTypeDefaultDescription
borderDashint[][]Length and spacing of dashes on grid lines. See MDN.
borderDashOffsetdouble0Offset for line dashes. See MDN.
colorString - IsColorDefaults.get().getGlobal()
.getBorderColorAsString()
Color of angled lines.
See default colors.
displaybooleantrueIf true, angle lines are shown.
lineWidthint1Width of angled lines.

PointLabels

The point labels options are used to configure the point labels that are shown on the perimeter of the scale.

The point labels configuration is nested in the scale configuration as following

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().getPointLabels().setColor(HtmlColor.RED);

IsColor color = Defaults.get().getScale().getPointLabels().getColor();

The following are the attributes that you can set:

NameTypeDefaultDescription
backdropColorString - IsColorDefaults.get().getGlobal()
.getBackgroundColorAsString()
Background color of the point label.
backdropPaddingPadding2 to all dimensionsThe padding of label backdrop.
See padding documentation for more details.
displaybooleantrueIf true, point labels are shown.
colorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
Color of point labels.
See default colors.
fontFontDefaults.get().getGlobal()
.getFont()
Font of point labels.
See Font.
paddingint5Padding between chart and point labels, in pixel.

Time

The time options are used to configure the time axis.

The time configuration is nested in the scale configuration as following:

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().getTime().setUnit(TimeUnit.DAY);

TimeUnit unit = Defaults.get().getScale().getTime().getUnit();

The following are the attributes that you can set:

NameTypeDefaultDescription
isoWeekdayIsoWeekDayIsoWeekDay.SUNDAYThe first day of the week.
minUnitTimeUnitTimeUnit.MILLISECONDThe minimum display format to be used for a time unit.
parserStringnullInterpreted as a custom format to be used to parse the date.
roundTimeUnitnullIf defined, dates will be rounded to the start of this unit.
stepSizeint1The number of units between grid lines.
tooltipFormatStringnullFormat string to use for the tooltip.
unitTimeUnitnullIf defined, will force the unit to be a certain type.

For more details, have a look how to configure a cartesian time axis.

Display formats

The display formats are used to configure how different time units are formed in the strings for the axis tick marks.

The display formats configuration is nested in the scale configuration as following:

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
// changes the default format (of date adapter) of a time unit
Defaults.get().getScale().getTime().getDisplayFormats().setDisplayFormat(TimeUnit.HOUR, "hh:MM:00");

String displayFormat = Defaults.get().getScale().getTime().getDisplayFormats().getDisplayFormat(TimeUnit.HOUR);

Adapters

The adapters options are used to configure the adapter for external date library if that adapter needs or supports options. The options are leveraging in INTL framework

The adapters options configuration is nested in the scale configuration as following:

// --------------------------------------
// GLOBAL, for all scales (whatever type)
// --------------------------------------
Defaults.get().getScale().getAdapters().setLocale(CLocale.ITALY);

CLocale locale = Defaults.get().getScale().getAdapters().getLocale();

The following are the attributes that you can set:

NameTypeDefaultDescription
localeCLocalenullUsing locale specifying the language to use generating or interpreting strings.
zoneTimeZonenullImplementation recognizes the time zone names of the IANA time zone database.
outputCalendarCalendarnullThe calendar type to use.
numberingSystemNumberingSystemnullThe numbering system to use.

For more details, have a look how to configure a Luxon date adapters and the locale documentation.