Indicators

Indicators display a single KPI scalar — optionally with a comparison delta and a graphical fill element. They are parallel to figure strategies: a strategy class accepts fields_metadata, aggregations, and rendering options; build() returns an IndicatorView containing rendered HTML.

from orama.indicators.text import TextIndicatorStrategy
from orama.variables import Aggregation

strategy = TextIndicatorStrategy(
    fields_metadata=fields_metadata,
    current_aggregation=Aggregation(name="revenue", function="sum", field="amount"),
    comparison_aggregation=Aggregation(name="prev_revenue", function="sum", field="amount"),
    delta_is_relative=True,
    title="Revenue",
)
view = strategy.build(dfs={"current": df_current, "comparison": df_prev}, tr=tr, theme=theme)
# view.html — rendered HTML string

get_query_params() returns the aggregation query parameters. The "current" key is always present; "comparison" is only present when comparison_aggregation is set.

Common parameters

All four indicator strategies share these base parameters:

IndicatorStrategy(
    fields_metadata=fields_metadata,          # dict[str, FieldMetadata]
    current_aggregation=Aggregation(...),     # primary KPI
    comparison_aggregation=None,              # Aggregation | None — enables delta
    delta_is_relative=False,                  # bool — show delta as % of comparison
    delta_position=DeltaPosition.BOTTOM,      # DeltaPosition or "top" / "bottom" / "right"
    current_font_size=None,                   # float | None — px; None → theme indicator_value
    delta_font_size=None,                     # float | None — px; None → theme indicator_delta
    title=None,                               # str | None
    subtitle=None,                            # str | None
    caption=None,                             # str | None
    description=None,                         # str | None
    storytelling_context=None,                # str | None
    current_color_rules=None,                 # list[ColorRule] | None
    delta_color_rules=None,                   # list[ColorRule] | None
    pre_build_callback=None,                  # Callable[[dict], None] | None
    post_build_callback=None,                 # Callable[[dict], None] | None
)

Unit auto-detection

If the aggregation field's FieldMetadata carries a "unit" key in its extra dict, the unit string is automatically picked up and rendered as a separate <span class="unit"> element next to the value:

from fields_metadata import FieldMetadata

fields_metadata = {
    "amount": FieldMetadata(name="Amount", extra={"unit": "EUR"}),
}

The unit appears after both the current value and, when present, the delta value.

Text Indicator

TextIndicatorStrategy renders only styled text — no graphical element.

from orama.indicators.text import TextIndicatorStrategy

strategy = TextIndicatorStrategy(
    fields_metadata=fields_metadata,
    current_aggregation=Aggregation(name="score", function="avg", field="score"),
    comparison_aggregation=Aggregation(name="prev_score", function="avg", field="score"),
    delta_is_relative=False,
    delta_position="bottom",                  # "top" | "bottom" | "right"
    title="Average Score",
)

No additional parameters beyond the common base.

Bar Indicator

BarIndicatorStrategy renders a rectangular progress bar alongside the text block.

from orama.indicators.bar import BarIndicatorStrategy
from orama.indicators.enums import BarPosition, BarRepresents, GraphicalFillMode

strategy = BarIndicatorStrategy(
    fields_metadata=fields_metadata,
    current_aggregation=Aggregation(name="progress", function="sum", field="completed"),
    domain_min=0.0,                           # float — bar left/bottom boundary
    domain_max=100.0,                         # float — bar right/top boundary
    bar_position=BarPosition.BELOW,           # BELOW | LEFT | RIGHT
    bar_represents=BarRepresents.CURRENT_VALUE,  # CURRENT_VALUE | DELTA
    graphical_fill_mode=GraphicalFillMode.GRADIENT,  # GRADIENT | FLAT
    bar_color="indicator_domain_track_color", # theme color name or "#hex" for the track
    linecap="round",                          # "round" | "butt"
    graphical_color_rules=None,               # list[ColorRule] | None
    current_font_size=48.0,
    delta_font_size=24.0,
    title="Completion",
)

bar_position controls layout:

Value	Layout
`BarPosition.BELOW`	Horizontal bar below the text block
`BarPosition.LEFT`	Vertical bar on the left, text on the right
`BarPosition.RIGHT`	Text on the left, vertical bar on the right

When bar_represents=BarRepresents.DELTA the fill grows from the bar midpoint outward and a centre-tick marker is drawn; comparison_aggregation must be provided.

Circle Indicator

CircleIndicatorStrategy renders a full-circle arc that fills clockwise from the top.

from orama.indicators.circle import CircleIndicatorStrategy
from orama.indicators.enums import CircleTextPosition, GraphicalFillMode

strategy = CircleIndicatorStrategy(
    fields_metadata=fields_metadata,
    current_aggregation=Aggregation(name="utilisation", function="avg", field="cpu"),
    domain_min=0.0,
    domain_max=100.0,
    text_position=CircleTextPosition.CENTER,  # CENTER | SIDE
    inside_delta_position="bottom",           # "top" | "bottom" — only for CENTER
    graphical_fill_mode=GraphicalFillMode.GRADIENT,
    bar_color="indicator_domain_track_color",
    linecap="round",
    graphical_color_rules=None,
    current_font_size=48.0,
    delta_font_size=24.0,
    title="CPU Utilisation",
)

text_position=CircleTextPosition.CENTER overlays the text inside the circle ring. CircleTextPosition.SIDE places the circle to the left and text to the right.

Arc Indicator

ArcIndicatorStrategy renders an open arc (270° or 180°) that fills from one end.

from orama.indicators.arc import ArcIndicatorStrategy
from orama.indicators.enums import ArcDegrees, ArcTextPosition, ArcRepresents, GraphicalFillMode

strategy = ArcIndicatorStrategy(
    fields_metadata=fields_metadata,
    current_aggregation=Aggregation(name="nps", function="avg", field="score"),
    domain_min=0.0,
    domain_max=100.0,
    arc_degrees=ArcDegrees.DEG_270,           # DEG_270 | DEG_180
    text_position=ArcTextPosition.CENTER,     # CENTER | SIDE
    arc_represents=ArcRepresents.CURRENT_VALUE,  # CURRENT_VALUE | DELTA
    inside_delta_position="bottom",           # "top" | "bottom" — only for CENTER
    graphical_fill_mode=GraphicalFillMode.GRADIENT,
    bar_color="indicator_domain_track_color",
    linecap="round",
    graphical_color_rules=None,
    current_font_size=48.0,
    delta_font_size=24.0,
    title="NPS",
)

ArcDegrees.DEG_270 leaves a gap at the bottom (gauge style). ArcDegrees.DEG_180 is a horizontal semicircle. When arc_represents=ArcRepresents.DELTA a centre-tick marks the midpoint.

CSS customisation

Every rendered indicator carries stable CSS class names. Inline styles control default appearance; classes let you override specific elements without !important specificity battles.

/* Example: make units smaller and de-emphasised */
.orama-indicator .unit {
  font-size: 0.65em;
  opacity: 0.6;
}

/* Example: capitalise all titles */
.orama-indicator .title {
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

/* Example: colour delta values uniformly */
.orama-indicator .delta-value {
  color: #94a3b8;
}

Class reference

Class	Element	Present when
`orama-indicator`	`<figure>` outer container	Always
`title`	`<p>`	`title` is set
`subtitle`	`<p>`	`subtitle` is set
`values`	`<div>` value/delta layout container	Always
`delta-bottom`	modifier on `.values`	`delta_position="bottom"` (default)
`delta-top`	modifier on `.values`	`delta_position="top"`
`delta-right`	modifier on `.values`	`delta_position="right"`
`current-value`	`<span>`	Always
`delta-value`	`<span>`	Comparison value is provided
`unit`	`<span>` inside `.current-value` / `.delta-value`	Unit is detected from field metadata
`arc-indicator`	`<div>`	`ArcIndicatorStrategy`
`arc-indicator-text-inside`	`<div>`	`text_position=CENTER`
`arc-indicator-text-side`	`<div>`	`text_position=SIDE`
`bar-indicator`	`<div>`	`BarIndicatorStrategy`
`bar-indicator-text-above`	`<div>`	`bar_position=BELOW` (text above horizontal bar)
`bar-indicator-text-right`	`<div>`	`bar_position=LEFT` (bar on left, text on right)
`bar-indicator-text-left`	`<div>`	`bar_position=RIGHT` (text on left, bar on right)
`circle-indicator`	`<div>`	`CircleIndicatorStrategy`
`circle-indicator-text-inside`	`<div>`	`text_position=CENTER`
`circle-indicator-text-side`	`<div>`	`text_position=SIDE`

Theme fonts

Two indicator-specific font slots are registered automatically on every Theme:

Slot	Kind	Default derivation
`indicator_value`	computed	Based on `_indicator_base_size`
`indicator_delta`	computed	Smaller than `indicator_value`

Override the base size by passing _indicator_base_size in the fonts dict:

from orama.theme import Font, Theme

theme = Theme(
    colors={...},
    fonts={
        "_indicator_base_size": Font('"Open Sans", sans-serif', 52.0, 700, False),
    },
)

Retrieve a font with theme.get_font("indicator_value").

Color rules

All indicator strategies accept current_color_rules and delta_color_rules to colour the text values. Graphical strategies additionally accept graphical_color_rules for the fill element.

Supported selectors: ColorSelectorStrategy, ColorSelectValuesBelow, ColorSelectValuesAbove.

Supported assigners: ColorAssignerByValue.

The last matching rule wins. When graphical_fill_mode=GraphicalFillMode.GRADIENT and at least one graphical rule uses ColorAssignerByValue, the fill is rendered as a continuous color gradient across the domain.