config/Options/shape/bar.ts

  1. /**
  2. * Copyright (c) 2017 ~ present NAVER Corp.
  3. * billboard.js project is licensed under the MIT license
  4. */
  5. /**
  6. * bar config options
  7. */
  8. export default {
  9. /**
  10. * Set bar options
  11. * @name bar
  12. * @memberof Options
  13. * @type {object}
  14. * @property {object} bar Bar object
  15. * @property {boolean} [bar.front=false] Set 'bar' to be positioned over(on the top) other shapes elements.
  16. * @property {number} [bar.indices.removeNull=false] Remove nullish data on bar indices positions.
  17. * @property {number} [bar.label.threshold=0] Set threshold ratio to show/hide labels.
  18. * @property {boolean|object} [bar.linearGradient=false] Set the linear gradient on bar.<br><br>
  19. * Or customize by giving below object value:
  20. * - x {Array}: `x1`, `x2` value (default: `[0, 0]`)
  21. * - y {Array}: `y1`, `y2` value (default: `[0, 1]`)
  22. * - stops {Array}: Each item should be having `[offset, stop-color, stop-opacity]` values.
  23. * - (default: `[[0, $DATA_COLOR, 1], [1, $DATA_COLOR, 0]]`)
  24. * @property {boolean} [bar.overlap=false] Bars will be rendered at same position, which will be overlapped each other. (for non-grouped bars only)
  25. * @property {number} [bar.padding=0] The padding pixel value between each bar.
  26. * @property {number} [bar.radius] Set the radius of bar edge in pixel.
  27. * @property {number} [bar.radius.ratio] Set the radius ratio of bar edge in relative the bar's width.
  28. * @property {number} [bar.sensitivity=2] The senstivity offset value for interaction boundary.
  29. * @property {number|Function|object} [bar.width] Change the width of bar chart.
  30. * @property {number} [bar.width.ratio=0.6] Change the width of bar chart by ratio.
  31. * - **NOTE:** Criteria for ratio.
  32. * - When x ticks count is same with the data count, the baseline for ratio is the minimum interval value of x ticks.
  33. * - ex. when timeseries x values are: [2024-01-01, 2024-02-01, 2024-03-01], the minimum interval will be `2024-02-01 ~ 2024-03-01`
  34. * - if the minimum interval is 30px, then ratio=1 means 30px.
  35. * - When x ticks count is lower than the data count, the baseline will be calculated as `chart width / data count`.
  36. * - ex. when chart width is 500, data count is 5, then ratio=1 means 100px.
  37. * @property {number} [bar.width.max] The maximum width value for ratio.
  38. * @property {number} [bar.width.dataname] Change the width of bar for indicated dataset only.
  39. * @property {number} [bar.width.dataname.ratio=0.6] Change the width of bar chart by ratio.
  40. * - **NOTE:**
  41. * - Works only for non-stacked bar
  42. * @property {number} [bar.width.dataname.max] The maximum width value for ratio.
  43. * @property {boolean} [bar.zerobased=true] Set if min or max value will be 0 on bar chart.
  44. * @see [Demo: bar front](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarFront)
  45. * @see [Demo: bar indices](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarIndices)
  46. * @see [Demo: bar overlap](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarOverlap)
  47. * @see [Demo: bar padding](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarPadding)
  48. * @see [Demo: bar radius](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarRadius)
  49. * @see [Demo: bar width](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarWidth)
  50. * @see [Demo: bar width variant](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarWidthVariant)
  51. * @example
  52. * bar: {
  53. * // make bar shape to be positioned over the other shape elements
  54. * front: true,
  55. *
  56. * // remove nullish data on bar indices postions
  57. * indices: {
  58. * removeNull: true
  59. * },
  60. *
  61. * // will generate follwing linearGradient:
  62. * // for more info: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient
  63. * // <linearGradient x1="0" x2="0" y1="0" y2="1">
  64. * // <stop offset="0" stop-color="$DATA_COLOR" stop-opacity="1"></stop>
  65. * // <stop offset="1" stop-color="$DATA_COLOR" stop-opacity="0"></stop>
  66. * // </linearGradient>
  67. * linearGradient: true,
  68. *
  69. * // Or customized gradient
  70. * linearGradient: {
  71. * x: [0, 0], // x1, x2 attributes
  72. * y: [0, 0], // y1, y2 attributes
  73. * stops: [
  74. * // offset, stop-color, stop-opacity
  75. * [0, "#7cb5ec", 1],
  76. *
  77. * // setting 'null' for stop-color, will set its original data color
  78. * [0.5, null, 0],
  79. *
  80. * // setting 'function' for stop-color, will pass data id as argument.
  81. * // It should return color string or null value
  82. * [1, function(id) { return id === "data1" ? "red" : "blue"; }, 0],
  83. * ]
  84. * },
  85. *
  86. * // remove nullish da
  87. * overlap: true,
  88. *
  89. * padding: 1,
  90. *
  91. * // bar radius
  92. * radius: 10,
  93. * // or
  94. * radius: {
  95. * ratio: 0.5
  96. * }
  97. *
  98. * label: {
  99. * // 0.1(10%) ratio value means, the minimum ratio to show text label relative to the y Axis domain range value.
  100. * // if data value is below than 0.1, text label will be hidden.
  101. * threshold: 0.1,
  102. * },
  103. *
  104. * // will not have offset between each bar elements for interaction
  105. * sensitivity: 0,
  106. *
  107. * width: 10,
  108. *
  109. * // or specify width callback. The callback will receive width, targetsNum, maxDataCount as arguments.
  110. * // - width: chart area width
  111. * // - targetsNum: number of targets
  112. * // - maxDataCount: maximum data count among targets
  113. * width: function(width, targetsNum, maxDataCount) {
  114. * return width / (targetsNum * maxDataCount);
  115. * }
  116. *
  117. * // or specify ratio & max
  118. * width: {
  119. * ratio: 0.2,
  120. * max: 20
  121. * },
  122. *
  123. * // or specify width per dataset
  124. * width: {
  125. * data1: 20,
  126. * data2: {
  127. * ratio: 0.2,
  128. * max: 20
  129. * }
  130. * },
  131. *
  132. * zerobased: false
  133. * }
  134. */
  135. bar_front: false,
  136. bar_indices_removeNull: false,
  137. bar_label_threshold: 0,
  138. bar_linearGradient: <boolean | {
  139. x?: [number, number],
  140. y?: [number, number],
  141. stops?: [number, string | null | Function, number]
  142. }>false,
  143. bar_overlap: false,
  144. bar_padding: 0,
  145. bar_radius: <number | {ratio: number} | undefined>undefined,
  146. bar_radius_ratio: <number | undefined>undefined,
  147. bar_sensitivity: 2,
  148. bar_width: <number | ((width: number, targetsNum: number, maxDataCount: number) => number) | {
  149. ratio?: number,
  150. max?: number
  151. } | undefined>undefined,
  152. bar_width_ratio: 0.6,
  153. bar_width_max: undefined,
  154. bar_zerobased: true
  155. };