@spec axis_label_rotation(t(), integer() | :auto) :: t()

Specifies the label rotation value that will be applied to the bottom axis. Accepts integer values for degrees of rotation or :auto. Note that manually set rotation values other than 45 or 90 will be treated as zero. The default value is :auto, which sets the rotation to zero degrees if the number of items on the axis is greater than eight, 45 degrees otherwise.

@spec colours(t(), Contex.CategoryColourScale.colour_palette()) :: t()

Overrides the default colours.

Colours can either be a named palette defined in Contex.CategoryColourScale or a list of strings representing hex code of the colour as per CSS colour hex codes, but without the #. For example:

  barchart = BarChart.colours(barchart, ["fbb4ae", "b3cde3", "ccebc5"])

The colours will be applied to the data series in the same order as the columns are specified in set_val_col_names/2

@spec custom_value_formatter(t(), nil | (... -> any())) :: t()

Allows the axis tick labels to be overridden. For example, if you have a numeric representation of money and you want to have the value axis show it as millions of dollars you might do something like:

  # Turns 1_234_567.67 into $1.23M
  defp money_formatter_millions(value) when is_number(value) do
    "$#{:erlang.float_to_binary(value/1_000_000.0, [decimals: 2])}M"
  end

  defp show_chart(data) do
    BarChart.new(data)
    |> BarChart.custom_value_formatter(&money_formatter_millions/1)
  end

@spec data_labels(t(), boolean()) :: t()

Specifies whether data labels are shown on the bars

Optionally specify a LiveView event handler. This attaches a phx-click attribute to each bar element. You can specify the event_target for LiveComponents - a phx-target attribute will also be attached.

Note that it may not work with some browsers (e.g. Safari on iOS).

@spec force_value_range(
  t(),
  {number(), number()}
) :: t()

Forces the value scale to the given data range

@spec new(
  Contex.Dataset.t(),
  keyword()
) :: t()

Creates a new barchart from a dataset and sets defaults.

Options may be passed to control the settings for the barchart. Options available are:

• :type : :stacked (default) or :grouped
• :orientation : :vertical (default) or :horizontal
• :axis_label_rotation : :auto (default), 45 or 90

Specifies the label rotation value that will be applied to the bottom axis. Accepts integer values for degrees of rotation or :auto. Note that manually set rotation values other than 45 or 90 will be treated as zero. The default value is :auto, which sets the rotation to zero degrees if the number of items on the axis is greater than eight, 45 degrees otherwise.

• :custom_value_scale : nil (default) or an instance of a suitable Contex.Scale.

The scale must be suitable for the data type and would typically be Contex.ContinuousLinearScale. It is not necessary to set the range for the scale as the range is set as part of the chart layout process.

• :custom_value_formatter : nil (default) or a function with arity 1

Allows the axis tick labels to be overridden. For example, if you have a numeric representation of money and you want to have the value axis show it as millions of dollars you might do something like:

  # Turns 1_234_567.67 into $1.23M
  defp money_formatter_millions(value) when is_number(value) do
    "$#{:erlang.float_to_binary(value/1_000_000.0, [decimals: 2])}M"
  end

  defp show_chart(data) do
    BarChart.new(
      dataset,
      mapping: %{category_col: :column_a, value_cols: [:column_b, column_c]},
      custom_value_formatter: &money_formatter_millions/1
    )
  end

• :padding : integer (default 2) - Specifies the padding between the category groups. Defaults to 2. Specified relative to the plot size.
• :data_labels : true (default) or false - display labels for each bar value
• :colour_palette : :default (default) or colour palette - see colours/2

Overrides the default colours.

Colours can either be a named palette defined in Contex.CategoryColourScale or a list of strings representing hex code of the colour as per CSS colour hex codes, but without the #. For example:

  barchart = BarChart.new(
      dataset,
      mapping: %{category_col: :column_a, value_cols: [:column_b, column_c]},
      colour_palette: ["fbb4ae", "b3cde3", "ccebc5"]
    )

The colours will be applied to the data series in the same order as the columns are specified in set_val_col_names/2

• :phx_event_handler : nil (default) or string representing phx-click event handler
• :phx_event_target : nil (default) or string representing phx-target for handler

Optionally specify a LiveView event handler. This attaches a phx-click attribute to each bar element. You can specify the event_target for LiveComponents - a phx-target attribute will also be attached.

Note that it may not work with some browsers (e.g. Safari on iOS).

• :select_item - optional selected item to highlight. See select_item/2.

• :mapping : Maps attributes required to generate the barchart to columns in the dataset.

If the data in the dataset is stored as a map, the :mapping option is required. If the dataset is not stored as a map, :mapping may be left out, in which case the first column will be used for the category and the second column used as the value. This value must be a map of the plot's :category_col and :value_cols to keys in the map, such as %{category_col: :column_a, value_cols: [:column_b, column_c]}. The value for the :value_cols key must be a list.

@spec orientation(t(), orientation()) :: t()

Specifies whether the bars are drawn horizontally or vertically.

@spec padding(t(), number()) :: t()

Specifies the padding between the category groups. Defaults to 2. Specified relative to the plot size.

@spec select_item(t(), selected_item()) :: t()

Highlights a selected value based on matching category and series.

Sets the category column name. This must exist in the dataset.

This provides the labels for each bar or group of bars

@spec set_default_scales(t()) :: t()

Sets the default scales for the plot based on its column mapping.

Sets the value column names. Each must exist in the dataset.

This provides the value for each bar.

@spec type(t(), plot_type()) :: t()

Specifies whether the bars are drawn stacked or grouped.