CategoryAxis

Type class

Extension for AxisBase, gets automatically populated if none has been specified.

Example

var chart = AmCharts.makeChart("chartdiv",{
  ...
  "categoryAxis": {
    "gridPosition": "start"
  }
});

Inheritance

CategoryAxis extends AxisBase.

CategoryAxis is not extended by any other symbol.

Properties

autoRotateAngle
#

Type number

Angle of label rotation, if the number of series exceeds autoRotateCount and parseDates is set to false.

autoRotateCount
#

Type number

If the number of category axis items will exceed the autoRotateCount, the labels will be rotated by autoRotateAngle degree. Works only if parseDates is false.

autoWrap
#

Type boolean

Default false

Specifies if axis labels (only when it is horizontal) should be wrapped if they don't fit in the allocated space. If axis is vertical, you should set axis.ignoreAxisWidth to true in order this feature to work.

categoryFunction
#

specifies a method that returns the value that should be used as categoryValue for current item. If this property is set, the return value of the custom data function takes precedence over categoryField. When a chart calls this method, it passes category value, data item from chart's data provider and reference to categoryAxis: categoryFunction(category, dataItem, categoryAxis); This method can be used both when category axis parses dates and when it doesn't. If axis parses dates, your categoryFunction should return Date object. For example, if you have date strings in your data, you can use this method to convert these strings into Date objects.

classNameField
#

Type string

If this field is set and addClassNames is enabled, the category axis labels, ticks and grid will have this class name set.

NOTE: this will not work if the axis is date-based.

dateFormats
#

Type object[]

Default [{
  "period":"fff",
  "format":"JJ:NN:SS"
}, {
  "period":"ss",
  "format":"JJ:NN:SS"
}, {
  "period":"mm",
  "format":"JJ:NN"
}, {
  "period":"hh",
  "format":"JJ:NN"
}, {
  "period":"DD",
  "format":"MMM DD"
}, {
  "period":"WW",
  "format":"MMM DD"
}, {
  "period":"MM",
  "format":"MMM"
}, {
  "period":"YYYY",
  "format":"YYYY"
}]

Date formats of different periods. Possible period values: fff - milliseconds, ss - seconds, mm - minutes, hh - hours, DD - days, MM - months, WW - weeks, YYYY - years. Check this page for date formatting strings.

equalSpacing
#

Type boolean

Default false

In case your category axis values are Date objects and parseDates is set to true, the chart will parse dates and will place your data points at irregular intervals. However if you want dates to be parsed (displayed on the axis, baloons, etc), but data points to be placed at equal intervals (omiting dates with no data), set equalSpacing to true.

forceShowField
#

Type string

Field in data provider which specifies if the category value should always be shown. For example: categoryAxis.forceShowField = "forceShow";

And in data:

{category:"one", forceShow:true, value:100} Note, this works only when parseDates is set to false.

gridPosition
#

Type string

Default middle

Specifies if a grid line is placed on the center of a cell or on the beginning of a cell. Possible values are: "start" and "middle" This setting doesn't work if parseDates is set to true.

labelColorField
#

Type string

You can use it to set color of a axis label. Works only with non-date-based data.

labelFunction
#

You can use this function to format Category axis labels. If this function is set, then it is called with the following parameters passed:

if dates are not parsed:

labelFunction(valueText, serialDataItem, categoryAxis) if dates are parsed:

labelFunction(valueText, date, categoryAxis) Your function should return string which will be displayed on the axis.

minPeriod
#

Type string

Default DD

Specifies the shortest period of your data. This should be set only if parseDates is set to "true". Possible period values: fff - milliseconds, ss - seconds, mm - minutes, hh - hours, DD - days, MM - months, YYYY - years.

It's also possible to supply a number for increments, i.e. "15mm" which will instruct the chart that your data is supplied in 15 minute increments.

parseDates
#

Type boolean

Default false

In case your category axis values are Date objects, set this to true. In this case the chart will parse dates and will place your data points at irregular intervals. If you want dates to be parsed, but data points to be placed at equal intervals, set both parseDates and equalSpacing to true.

Note: we recommend using JavaScript timestamps to specify date/time. If you are specifying dates as strings in your data, i.e. "2015-01-05", we strongly recommend setting dataDateFormat as well.

Important: If this is set to true, the data points needs to come pre-ordered in ascending order. Data with incorrect order might result in visual and functional glitches on the chart.

position
#

Type string

Default bottom

Possible values are: "top", "bottom", "left", "right". If axis is vertical, default position is "left". If axis is horizontal, default position is "bottom".

startOnAxis
#

Type boolean

Default false

Specifies whether the graph should start on axis or not. In case you display columns, it is recommended to set this to false. If parseDates is set to true, startOnAxis will allways be false, unless equalSpacing is set to true.

tickPosition
#

Type string

Default middle

Position of a axis tick. Available settings: middle, start. Works only with non-date-based data.

twoLineMode
#

Type boolean

Default false

Works only when parseDates is set to true and equalSpacing is false. If you set it to true, at the position where bigger period changes, category axis will display date strings of bot small and big period, in two rows.

widthField
#

Type string

You can specify relative width for your columns using this field and produce Mekko chart using this new feature.

autoGridCount
#

Type boolean

Default true

Inherited from AxisBase

Specifies whether number of gridCount is specified automatically, acoarding to the axis size.

axisAlpha
#

Type number

Default 1

Inherited from AxisBase

Axis opacity. Value range is 0 - 1.

axisColor
#

Type color

Default #000000

Inherited from AxisBase

Axis color.

axisThickness
#

Type number

Default 1

Inherited from AxisBase

Thickness of the axis.

boldLabels
#

Type boolean

Default false

Inherited from AxisBase

Specifies if axis labels should be bold or not.

boldPeriodBeginning
#

Type boolean

Default true

Inherited from AxisBase

When parse dates is on for the category axis, the chart will try to highlight the beginning of the periods, like month, in bold. Set this to false to disable the functionality.

centerLabelOnFullPeriod
#

Type boolean

Default true

Inherited from AxisBase

This setting works only when parseDates is set to true and equalSpacing is set to false. In case you set it to false, labels will never be centered between grid lines.

centerLabels
#

Type boolean

Default false

Inherited from AxisBase

Force-centers labels of date-based axis (in case it's category axis, equalSpacing must be false)

centerRotatedLabels
#

Type boolean

Default false

Inherited from AxisBase

In case you have rotated labels on horizontal axis, you can force-center them using this property.

color
#

Type color

Inherited from AxisBase

Color of axis value labels. Will use chart's color if not set.

dashLength
#

Type number

Default 0

Inherited from AxisBase

Length of a dash. 0 means line is not dashed.

fillAlpha
#

Type number

Default 0

Inherited from AxisBase

Fill opacity. Every second space between grid lines can be filled with color. Set fillAlpha to a value greater than 0 to see the fills.

fillColor
#

Type color

Default #FFFFFF

Inherited from AxisBase

Fill color. Every second space between grid lines can be filled with color. Set fillAlpha to a value greater than 0 to see the fills.

firstDayOfWeek
#

Type number

Default 1

Inherited from AxisBase

Sets first day of the week. 0 is Sunday, 1 is Monday, etc.

fontSize
#

Type number

Inherited from AxisBase

Size of value labels text. Will use chart's fontSize if not set.

gridAlpha
#

Type number

Default 0.15

Inherited from AxisBase

Opacity of grid lines.

gridColor
#

Type color

Default #000000

Inherited from AxisBase

Color of grid lines.

gridCount
#

Type number

Default 5

Inherited from AxisBase

Number of grid lines. In case this is value axis, or your categoryAxis parses dates, the number is approximate. The default value is 5. If you set autoGridCount to true, this property is ignored.

gridThickness
#

Type number

Default 1

Inherited from AxisBase

Thickness of grid lines.

guides
#

Type Guide[]

Default []

Inherited from AxisBase

The array of guides belonging to this axis.

ignoreAxisWidth
#

Type boolean

Default false

Inherited from AxisBase

If autoMargins of a chart is set to true, but you want this axis not to be measured when calculating margin, set ignoreAxisWidth to true.

inside
#

Type boolean

Default false

Inherited from AxisBase

Specifies whether values should be placed inside or outside plot area.

labelFrequency
#

Type number

Default 1

Inherited from AxisBase

Frequency at which labels should be placed. Doesn't work for CategoryAxis if parseDates is set to true.

labelOffset
#

Type number

Default 0

Inherited from AxisBase

You can use it to adjust position of axes labels. Works both with CategoryAxis and ValueAxis.

labelRotation
#

Type number

Default 0

Inherited from AxisBase

Rotation angle of a label. Only horizontal axis' values can be rotated. If you set this for vertical axis, the setting will be ignored. Possible values from -90 to 90.

labelsEnabled
#

Type boolean

Default true

Inherited from AxisBase

Specifies whether axis displays category axis' labels and value axis' values.

listeners
#

Type object[]

Inherited from AxisBase

You can add listeners of events using this property. Example: listeners = [{"event":"clickItem", "method":handleEvent}];

markPeriodChange
#

Type boolean

Default true

Inherited from AxisBase

If you set it to false, the start of longer periods won't use a different date format and won't be bold.

minHorizontalGap
#

Type number

Default 75

Inherited from AxisBase

This property is used when calculating grid count (when autoGridCount is true). It specifies minimum cell width required for one span between grid lines.

minorGridAlpha
#

Type number

Default 0.07

Inherited from AxisBase

Opacity of minor grid. In order minor to be visible, you should set minorGridEnabled to true.

minorGridEnabled
#

Type boolean

Default false

Inherited from AxisBase

Specifies if minor grid should be displayed.

NOTE: If equalSpacing is set to true, this setting will be ignored.

minorTickLength
#

Type number

Default 0

Inherited from AxisBase

Length of minor grid tick.

minVerticalGap
#

Type number

Default 35

Inherited from AxisBase

This property is used when calculating grid count (when autoGridCount is true). It specifies minimum cell height required for one span between grid lines.

offset
#

Type number

Default 0

Inherited from AxisBase

The distance of the axis to the plot area, in pixels. Negative values can also be used.

showFirstLabel
#

Type boolean

Default true

Inherited from AxisBase

Whether to show first axis label or not. This works properly only on ValueAxis. With CategoryAxis it wont work 100%, it depends on the period, zooming, etc. There is no guaranteed way to force category axis to show or hide first label.

showLastLabel
#

Type boolean

Default true

Inherited from AxisBase

Whether to show last axis label or not. This works properly only on ValueAxis. With CategoryAxis it wont work 100%, it depends on the period, zooming, etc. There is no guaranteed way to force category axis to show or hide last label.

tickLength
#

Type number

Default 5

Inherited from AxisBase

Length of the tick marks.

title
#

Type string

Inherited from AxisBase

Title of the axis.

titleBold
#

Type boolean

Default true

Inherited from AxisBase

Specifies if title should be bold or not.

titleColor
#

Type color

Inherited from AxisBase

Color of axis title. Will use text color of chart if not set any.

titleFontSize
#

Type number

Inherited from AxisBase

Font size of axis title. Will use font size of chart plus two pixels if not set any.

titleRotation
#

Type number

Inherited from AxisBase

Rotation of axis title. Useful if you want to make vertical axis title to be shown from top to down.

There are 42 inherited items currently hidden from this list.

Methods

addGuide(
  guide
)

#

Returns void

Inherited from AxisBase

Adds guide to the axis.

guide - instance of Guide

categoryToCoordinate(
  category
)

#

Returns Number

returns coordinate of a category. Works only if parseDates is false. If parseDates is true, use dateToCoordinate method.

category - String

coordinateToDate(
  coordinate
)

#

Returns date - Date object

Returns Date of the coordinate, in case parseDates is set to true and equalSpacing is set to false.

coordinate - Number

dateToCoordinate(
  date
)

#

Returns Number

Returns coordinate of the date, in case parseDates is set to true. if parseDates is false, use categoryToCoordinate method.

date - Date object

removeGuide(
  guide
)

#

Returns void

Inherited from AxisBase

Removes guide from the axis.

guide - instance of Guide

xToIndex(
  x
)

#

Returns Number

Returns index of the category which is most close to specified coordinate.

x - coordinate

There are 2 inherited items currently hidden from this list.

Events

#clickGuide

Param {type: "clickGuide", guide:Guide, chart:AmRectangularChart}

Inherited from AxisBase

Dispatched when user clicks on a guide.

#clickItem

Param {type: "clickItem", value:value, serialDataItem:SerialDataItem, axis:AxisBase, target:label, chart:AmRectangularChart, event:MouseEvent}

Inherited from AxisBase

Fired if user clicks on axis label.

#rollOutGuide

Param {type: "rollOutGuide", guide:Guide, chart:AmRectangularChart}

Inherited from AxisBase

Dispatched when user rolls-out of the guide.

#rollOutItem

Param {type: "rollOutItem", value:value, serialDataItem:SerialDataItem, axis:AxisBase, target:label, chart:AmRectangularChart, event:MouseEvent}

Inherited from AxisBase

Fired if user rolls-out of the axis label.

#rollOverGuide

Param {type: "rollOverGuide", guide:Guide, chart:AmRectangularChart}

Inherited from AxisBase

Dispatched when user rolls-over some guide.

#rollOverItem

Param {type: "rollOverItem", value:value, serialDataItem:SerialDataItem, axis:AxisBase, target:label, chart:AmRectangularChart, event:MouseEvent}

Inherited from AxisBase

Fired if user rolls-over axis label.

There are 6 inherited items currently hidden from this list.

Adapters

CategoryAxis does not have any adapters.