Theming
Apply a shared theme, override a token, and let the user choose light, dark or system appearance.
On this page
Apply a theme to a region
Shared theme and size
open FSharp.ViewEngine
open Acme.Components
open type Html
open type Datastar
let themedControls =
let theme =
ComponentsTheme.emerald
|> ComponentsTheme.withRadius Radius.Large
|> ComponentsTheme.withControlSize Size.Small
div {
_class ("grid gap-4 " + ComponentsTheme.className theme)
fveField {
fveLabel {
_for "theme-name"
"Name"
}
fveInput {
_id "theme-name"
_name "name"
_placeholder "Your name"
}
}
fveButton {
_class "justify-self-start"
_color Color.Primary
_variant ButtonVariant.Solid
"Save"
}
}A theme applies to its owning region and its components. This example selects Emerald, larger corners and Small controls; it does not change the surrounding page.
Override only what you need
Custom control radius
open FSharp.ViewEngine
open Acme.Components
open type Html
open type Datastar
let customRadius =
div {
_style "--fve-radius-control:1rem"
fveButton { "Rounded action" }
}Use ordinary classes and semantic CSS variables for local changes. Edit the installed source when the component structure itself needs to change.
Neutral interactive controls paint a translucent background wash without fading their content or replacing their selected color. --fve-hover-wash defaults to black at 5% in light mode and white at 10% in dark mode; --fve-pressed-wash uses 10% and 15%. Override these on the owning region, not the opaque --fve-surface or --fve-surface-hover tokens.
.quiet-region {
--fve-hover-wash: light-dark(rgb(0 0 0 / 0.05), rgb(255 255 255 / 0.10));
--fve-pressed-wash: light-dark(rgb(0 0 0 / 0.10), rgb(255 255 255 / 0.15));
}Table rows keep an opaque hover fill so sticky cells match. Use Table’s --fve-table-row-hover override for a table-specific color.
For an action-specific color palette, see Button. The update instructions explain how local edits are preserved.
Scope CSS variables to a region
Put overrides on the owning ComponentsTheme region or the specific component. A nested theme resets its own defaults; an explicit component _size or _density can set more-local values. Ordinary inherited overrides never need a new theme or a JavaScript observer.
Scoped light/dark overrides
open FSharp.ViewEngine
open Acme.Components
open type Html
open type Datastar
let scopedTokens =
div {
_id "theming-scoped-controls"
_class (ComponentsTheme.className ComponentsTheme.emerald + " grid gap-4")
_style "--fve-radius-control:0.75rem;--fve-hover-wash:light-dark(rgb(0 0 0 / 0.07),rgb(255 255 255 / 0.12));--fve-pressed-wash:light-dark(rgb(0 0 0 / 0.12),rgb(255 255 255 / 0.18));--fve-primary-hover:light-dark(#166534,#34d399);--fve-primary-active:light-dark(#14532d,#10b981)"
fveButton { _color Color.Primary; _variant ButtonVariant.Solid; "Save changes" }
fveLink { _href "/components/button"; _color Color.Neutral; _variant LinkVariant.Outline; "Button reference" }
}The F# example uses _style for locality. The equivalent stylesheet can target the same region ID; light-dark() follows that region’s color-scheme, including manual appearance preferences.
#theming-scoped-controls {
--fve-radius-control: 0.75rem;
--fve-hover-wash: light-dark(rgb(0 0 0 / 0.07), rgb(255 255 255 / 0.12));
--fve-pressed-wash: light-dark(rgb(0 0 0 / 0.12), rgb(255 255 255 / 0.18));
--fve-primary-hover: light-dark(#166534, #34d399);
--fve-primary-active: light-dark(#14532d, #10b981);
}CSS-variable reference
These are the supported customization variables. Defaults below come from ComponentsTheme.sky with its default Medium controls and Comfortable density, before application overrides. Other named themes change the brand values; changing appearance selects the corresponding mode. The catalog itself uses Compact density.
Search by variable name, purpose or scope, or filter to theme defaults, action palettes or component overrides. Each variable appears once, with ten results per page.
Each of the seven built-in action colors has independently overridable fields. The reference reads the actual palette fallbacks and shared Sky semantic defaults; var(...) defaults follow the owning theme. Neutral, Warning and Info text variables also serve their corresponding semantic controls. Neutral Outline/Ghost actions use the shared background-wash tokens instead of the opaque Soft fills. Color.Custom uses its supplied ColorPalette, rather than these built-in token defaults.
| Variable | Purpose / owning scope | Light default | Dark default |
|---|---|---|---|
--fve-table-row-hover | Opaque hover fill; sticky cells reuse it, selected rows keep their own fill Table or region; only applies when _hoverRows true | Table background mixed with 5% black | Table background mixed with 10% white |
--fve-chart-height | Plot height Chart host; inherited into its shadow-DOM plot | 18rem | 18rem |
--fve-calendar-viewport-height | Maximum timed Day/Week viewport height Calendar region; an explicit _viewportHeight writes a local value | 38rem | 38rem |
--fve-slide-cover-background | Cover canvas background Cover Slide or its containing region | #101828 | #101828 |
--fve-slide-cover-text | Cover foreground Cover Slide; also sets its local --fve-text | white | white |
--fve-slide-cover-muted | Cover secondary text Cover Slide; also sets its local --fve-muted-text | #d1d5db | #d1d5db |
--fve-docs-code-surface | CodeBlock/CodeFrame background (historical token name) CodeBlock/CodeFrame or surrounding region | color-mix(in oklch, var(--fve-background) 72%, var(--fve-surface-subtle)) | color-mix(in oklch, var(--fve-background) 72%, var(--fve-surface-subtle)) |
Internal variables
Variables prefixed --fve-internal- are component-managed implementation details. Use the customization variables listed above.
Add an appearance picker
After Installation, add the initializer and radio controls:
dotnet fve add color-mode radio-group --config src/Acme.Components/fve.jsonAdd the initializer before the stylesheet in your existing head. The key identifies the browser-local preference shared by the controls in that document.
open FSharp.ViewEngine
open Acme.Components
open type Html
open type Datastar
let appearanceHead =
head {
ColorMode.assets "my-app-appearance" ColorMode.System
link {
_rel "stylesheet"
_href "/css/output.css"
}
}Appearance
open FSharp.ViewEngine
open Acme.Components
open type Html
open type Datastar
let appearancePicker =
fveRadioGroup {
_dataSignals "{_guide_appearance: window.fveColorMode.current()}"
_dataOn ("fve-color-mode", ["window"], "$_guide_appearance = window.fveColorMode.current()")
yield! ColorMode.nativeChoiceAttributes
fveFieldLegend { "Appearance" }
for value, label in [ "system", "System"; "light", "Light"; "dark", "Dark" ] do
let selected = value = "system"
fveLabel {
fveRadio {
_name "guide-appearance"
_value value
_checked selected
_dataBind "_guide_appearance"
}
label
}
}The radios bind to the saved preference and follow changes from other controls. System stays selected while the operating system decides the resolved appearance. This preview uses the catalog's existing preference.
For a nonce-enabled host, use ColorMode.assetsWithNonce and the existing CSP setup. The Profile example shows the appearance picker in a working app. It uses the regular application script; no separate appearance bundle is needed.
Theme API
type Size =
| ExtraSmall
| Small
| Medium
| Large
| ExtraLarge
type Padding =
| Default
| Uniform
type Color =
| Primary
| Secondary
| Success
| Warning
| Error
| Info
| Neutral
| Custom
type Orientation =
| Horizontal
| Vertical
type Radius =
| None
| Medium
| Large
| Full
type Density =
| Compact
| Comfortable
type ComponentsTheme
type ColorPaletteMode =
{ solid: string
solidHover: string
solidActive: string
onSolid: string
soft: string
softHover: string
softActive: string
text: string
border: string
focus: string }
type ColorPalette =
{ light: ColorPaletteMode
dark: ColorPaletteMode }
type ColorMode =
| System
| Light
| Dark
module ColorMode =
val value : _arg1:ColorMode -> string
val assetsWithNonce : storageKey:string -> defaultMode:ColorMode -> nonce:string option -> HtmlElement
val assets : storageKey:string -> defaultMode:ColorMode -> HtmlElement
val nativeChoiceAttributes : HtmlAttribute list
module PaletteAttributes =
val Html._palette.Static : value:ColorPalette -> HtmlAttribute
module ComponentsTheme =
val custom : paletteClass:string -> ComponentsTheme
val withRadius : radius:Radius -> theme:ComponentsTheme -> ComponentsTheme
val withDensity : density:Density -> theme:ComponentsTheme -> ComponentsTheme
val withControlSize : size:Size -> theme:ComponentsTheme -> ComponentsTheme
val className : theme:ComponentsTheme -> string
val attributes : theme:ComponentsTheme -> HtmlAttribute list
val sky : ComponentsTheme
val emerald : ComponentsTheme
val amber : ComponentsTheme
val cyan : ComponentsTheme
val neutral : ComponentsTheme
module ComponentAttributes =
val Html._color.Static : value:Color -> HtmlAttribute
val Html._variant.Static : value:ButtonVariant -> HtmlAttribute
val Html._variant.Static : value:LinkVariant -> HtmlAttribute
val Html._variant.Static : value:BadgeVariant -> HtmlAttribute
val Html._size.Static : value:Size -> HtmlAttribute
val Html._padding.Static : value:Padding -> HtmlAttribute
val Html._underline.Static : value:LinkUnderline -> HtmlAttribute
val Html._values.Static : value:string list -> HtmlAttribute
val Html._expanded.Static : value:bool -> HtmlAttribute
val Html._clearable.Static : value:bool -> HtmlAttribute
val Html._announcement.Static : value:LiveAnnouncement -> HtmlAttribute
val Html._description.Static : value:string -> HtmlAttribute
val Html._trend.Static : value:string -> HtmlAttribute
val Html._persistenceKey.Static : value:string -> HtmlAttribute
val Html._orientation.Static : value:Orientation -> HtmlAttribute
val Html._density.Static : value:Density -> HtmlAttribute
module Size =
val className : _arg1:Size -> string