Documentation
¶
Overview ¶
Package format provides display-formatting helpers for dashboards, tables, and detail views: byte counts, durations, percentages, compact counts, and the empty-value placeholder. Pure functions, no dependencies, graceful on edge inputs (zero, negative, NaN, overflow) — a formatter must never panic in a render path.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bytes ¶
Bytes formats a byte count using IEC binary units (B, KiB, MiB, …, EiB): one decimal below ten of a unit ("1.5 KiB"), integers above ("42 MiB"), plain bytes below 1024 ("512 B"), and "0 B" for zero. The sign is preserved for negative counts ("-1.5 KiB").
Example ¶
package main
import (
"github.com/larsartmann/templ-components/utils/format"
)
func main() {
_ = format.Bytes(1536) // "1.5 KiB"
_ = format.Bytes(44_040_192) // "42 MiB"
_ = format.Bytes(-512) // "-512 B"
}
Output:
func ClockDuration ¶
ClockDuration renders a duration for display: "M:SS" under an hour ("3:45"), "H:MM:SS" under a day ("1:02:03"), and "Nd Hh" from a day up ("2d 5h" — dashboard uptime convention). Negative durations clamp to "0:00": elapsed-time UIs have no meaningful negative. Sub-second components are dropped.
Example ¶
package main
import (
"time"
"github.com/larsartmann/templ-components/utils/format"
)
func main() {
_ = format.ClockDuration(225 * time.Second) // "3:45"
_ = format.ClockDuration(3723 * time.Second) // "1:02:03"
_ = format.ClockDuration(53 * time.Hour) // "2d 5h"
}
Output:
func CompactCount ¶
CompactCount formats a count with magnitude suffixes: plain below 1,000 ("999"), then "k", "M", "B", "T" with one decimal below ten of a unit ("1.2k", "3.4M") and integers above ("42k", "1.2M"). The sign is preserved ("-2.5k").
func CompactDuration ¶
CompactDuration renders a duration the way operators write it in env vars: "42s", "1m30s", "12h30m", "1h" — Go's h/m/s units without the padded trailing "0s" that time.Duration.String produces for round values. Zero renders "0s", sub-second components are dropped (truncation toward zero), and negative durations keep their sign ("-1m30s").
Example ¶
package main
import (
"time"
"github.com/larsartmann/templ-components/utils/format"
)
func main() {
_ = format.CompactDuration(42 * time.Second) // "42s"
_ = format.CompactDuration(90 * time.Second) // "1m30s"
_ = format.CompactDuration(12*time.Hour + 30*time.Minute) // "12h30m"
}
Output:
func Percent ¶
Percent formats a 0–1 ratio as a percentage with one decimal ("87.3%"). Values above 1 render honestly ("150.0%" — capacity overcommit is real information) and negatives keep their sign. NaN and infinities degrade to the em-dash placeholder instead of rendering "NaN%" in a UI.
Example ¶
package main
import (
"math"
"github.com/larsartmann/templ-components/utils/format"
)
func main() {
_ = format.Percent(0.873) // "87.3%"
_ = format.Percent(1.5) // "150.0%"
_ = format.Percent(math.NaN()) // "—" placeholder
}
Output:
func StringOrDash ¶
StringOrDash renders s, or the em-dash placeholder when s is empty — the table and detail-view convention for absent values.
Types ¶
This section is empty.
Source Files