Charts
ChartLabels
Tick text and axis titles for a cartesian plot, positioned from ticks a chart has already computed. Paired with `ChartAxes`, which draws the rules for the same ticks.
<UiChartLabels :plot="..." :height="..." />Needs the charts module
This component ships in @jgastager/bundy-ui/charts, a separate module so projects that never draw a chart don't carry the paint classes these need. Nothing extra to install — just add the module entry. See Charts.
Options
One block per prop — what it does, and what it looks like set.
Plot
requiredplot is the rectangle the ticks were placed against — the same one the frame hands your slot, and the same one you built the scales from. Everything here is positioned relative to it, which is why the labels and the marks can't drift apart. It's separate from ChartAxes because a chart usually wants the rules *behind* its marks and the text in front, so render this one last: SVG paints in document order.
Render it *after* your marks in the slot, not before. SVG paints in document order, so labels written first end up under the bars.
Height
requiredheight is the chart's full height — not the plot's. It's needed because the x axis title sits against the bottom edge of the whole chart rather than the bottom of the plot, below the tick row. The frame hands it to your slot alongside plot, so pass that through.
X ticks
xTicks are the ticks along the horizontal axis, already positioned — each a value, an offset in pixels and the label to print. placeTicks(values, scale) builds them from a scale you already have. Omit them and the axis simply goes unlabelled, which is what you want on a chart whose categories are named in a legend instead.
Y ticks
yTicks are the ticks along the vertical axis, in the same shape. Pair them with the ones you hand ChartAxes — the rules and their labels have to come from the same array, or the numbers end up describing gridlines they don't sit on.
X label
xLabel is the title under the horizontal axis, naming what the ticks are counting. It renders dimmed and font-medium where the tick labels are muted and regular — quieter, because the reader needs a title once and the ticks continuously. The frame has to know it's coming: pass has-x-label so it reserves the extra row, or the title is drawn outside the margins.
Y label
yLabel is the title beside the vertical axis, rotated to run along it. It needs has-y-label on the frame for the same reason xLabel needs has-x-label — the margin is reserved before anything is measured. Skip it when the tick labels already carry their unit; two titles on a chart with four numbers is more chrome than information.
X tick size
xTickSize is the box the x-tick slot draws into — 24px square by default, sitting exactly where the label would have. Hand the frame the same number: it fixes the margins before this component renders, so content larger than the room booked for it hangs off the chart.
The box is square, and only one of its sides is ever reserved: its height below the plot for an x tick, its width beside the plot for a y tick. Content that isn't square is fine — size it by the dimension that axis actually books, and remember an x tick centred on the plot's edge hangs half its width outside.
The slot replaces the label, not the tick: placeTicks still decides which values get one, and tick.label is the formatted text you'd have got. Return an empty label from the formatter to drop a tick entirely, exactly as with text.
Y tick size
yTickSize is the same box on the left axis, and there the number is the whole margin — with a y-tick slot there are no label strings for the frame to estimate one from. An <image> takes box as it comes; anything centred on the tick takes x and y instead.
SVG content only — the slot renders inside the chart's <svg>. <UiIcon> works directly (it *is* an svg, so :x/:y position it) as do <image>, <text> and <use>; for ordinary HTML, wrap it in <foreignObject v-bind="box">.
Examples
The component in real use: compositions that answer "how do I build X with this", rather than one prop at a time.
Formatting and dropping ticks
placeTicks takes a formatter as its third argument, and returning an empty string drops that label entirely. That's how a long axis stays readable — here every other month is unlabelled. The frame reserves its margins from the labels you hand it, so pass the *formatted* strings or it will hold room for text that never renders.
Tick text and axis titles, positioned from ticks a chart has already placed. Pair it with ChartAxes, which draws the rules for the same ticks.
Tick labels are muted and axis titles dimmed, both at full opacity — the title is the quieter of the two, since it names an axis the reader already understands while the ticks carry the actual values. The grid is what fades back, not the text; don't restate that hierarchy with opacity of your own.
Spacing comes from chartAxisMetrics, not from numbers written here. The same constants set the margin useChartLayout reserves and the offset this component draws at — widen a gap in one place only and the labels either clip or float in dead space.
Two lines in one tick
The slot isn't only for pictures — it's whatever SVG you hand it, positioned for you. A date split over two lines is the common case: the month stays readable at a glance and the year stops repeating itself across the axis. Size the box for both lines, since the room below the plot was booked from that number.
API Reference
Generated from the component's source — props, slots and emits as the component actually declares them.
Props
number24Slots
x-ticky-tickTypes
interface ChartTick {
value: string | number;
offset: number;
label: string;
}interface ChartPlot {
x: number;
y: number;
width: number;
height: number;
/** Right edge, since marks need it more often than the width. */
right: number;
/** Bottom edge, which is also the x axis' baseline. */
bottom: number;
}