Aliases

Aliases are shortcut class names that expand to one or more Maple utilities before parsing and merge checks run.

Built-in Aliases

Maple includes built-in aliases for common utilities. They can be used directly, or with @:


<!--Both examples apply display: flex -->
<div class="fx"></div>
<div class="@fx"></div>

Custom Aliases

You can define custom aliases on the root <html> element using --alias-{name}=.... Custom aliases must be used with @. Use ; to separate multiple classes inside an alias:


<html class="--alias-truncate=of=hidden;tof=ellipsis;ws=nowrap">
  <span class="@truncate w-40">
    Long text that should truncate
  </span>
</html>

<html class="--alias-focus-ring=olw-2px;olst=solid;olc=currentColor;oloff-2">
  <button class="@focus-ring">Focusable control</button>
</html>

Alias Rules

Alias definitions are collected only from <html> and definitions on other elements are ignored. If the same custom alias is defined more than once on <html>, the later definition wins.

Pro Tip

You can use an alias at any scale. A small alias does one styling job, for example truncate. A large alias can hold all the styles for an element that repeats across your pages, such as a button or a card. This site styles its own buttons and notes with the custom aliases @btn and @note. An alias holds classes only. The markup for the element must come from somewhere else. If you build with a framework, put each repeated element in a component or a template and keep the shared styles in aliases. Plain HTML has no component layer. There, a large alias gives the repeated styles one home.

Invalid Usage

Alias definitions must be plain root classes. If you combine --alias-* with a media query or selector, Maple treats it like a normal CSS custom variable utility:


<!-- Invalid alias usage. They will resolve to "--alias-focus-ring" css variable. -->
<div class="md:--alias-focus-ring=olw-2px"></div>
<div class="&:hover:--alias-focus-ring=olw-2px"></div>

However, the classes inside an alias definition may include their own media queries and selectors. When you use the alias with an additional media query or selector, Maple composes the usage context with each expanded alias member:


<html class="--alias-focus-ring=@supports=[outline:1px_solid_currentColor]:&:focus-visible:olw-2px;&:focus-visible:olst=solid;&:focus-visible:olc=currentColor">
  <button class="@focus-ring"></button>
  <button class="@md:@focus-ring"></button>
  <button class="&:not(:disabled):@focus-ring"></button>
</html>

In this example, @md:@focus-ring applies the whole alias at the md viewport breakpoint while preserving the alias member's own @supports and &:focus-visible contexts. &:not(:disabled):@focus-ring also composes safely with the alias focus selector.

Alias Namespacing

User-defined aliases do not conflict with or override built-in utility names. If you define --alias-fx=d-grid, then @fx uses your alias, while bare fx still uses Maple's built-in flex alias.

Alias Reactivity

Aliases are not reactive. The alias set is read from <html> once, when the runtime starts, and locked for the lifetime of the page. Adding, changing, or removing --alias-* definitions after that point has no effect, and the change is ignored silently.

The lock is what keeps alias resolution deterministic: identical markup always produces the same rules regardless of when it is processed, so an element rendered late cannot pick up a different expansion than the same element rendered during the initial pass. A late definition is easy to miss because nothing visibly fails, so enable debug mode when an alias appears to do nothing.

Use Variables for Live Changes

Treat aliases as root-level configuration for reusable utility shortcuts, defined in your document's initial markup. When a value has to change while the page is running, put it in a CSS variable instead; variables stay live for the whole session.

Parameterized Aliases

Aliases can accept parameters using {name} placeholders. This allows you to create incredibly flexible, reusable utility abstractions that adapt dynamically to your design needs, bridging the gap between static utility classes and dynamic components.

When an alias expects a single value, you can pass it positionally. When passing multiple values, use named parameters. You can provide a default value by adding it after the comma in the placeholder definition (e.g., {name,default}):


<html class="--alias-underline=brc-{color,body}-900;pb-{space,2}">
  <a class="@underline(primary)">Primary underline</a>
  <a class="@underline(color:accent,space:3)">Accent underline</a>
</html>

If a parameter value contains a comma—such as an rgba color or a CSS function—wrap the value in brackets so Maple correctly splits the parameter list:


<html class="--alias-swatch=bgc={color}">
  <div class="@swatch([rgba(0,0,0,1)])"></div>
</html>

Nested Forwarding

Parameterized aliases can seamlessly forward arguments into nested aliases, unlocking advanced architectural patterns and deep composition directly in your HTML:


<html class="--alias-background=bgc-{color,body} --alias-card=@background({color});p-{space,2}">
  <article class="@card(primary)"></article>
</html>

Practical Example: Dynamic Component System

By combining parameterized aliases with nested forwarding, you can build entire component systems directly in your root HTML. Here is a real-world example from Maple's own website showing a highly reusable, variant-driven button system:


<!--
  1. @ihover: Define an interactive hover wrapper
  2. @theme: Define a base theme with dynamic colors
  3. @solid, @soft, @outline: Create variants that inherit from the theme
  4. @btn: Construct the dynamic button alias 
-->

<!doctype html>
<html lang="en" class="
  --alias-ihover=&:where(a,button,[tabindex]):hover:{utility}

  --alias-theme=br;c-{color,black}-600;@ihover(c-{color,black}-50);@ihover(bgc-{color,black}-350)

  --alias-solid=@theme({color});bgc-{color,black}-500;brc-transparent;c-{color,black}-50
  --alias-soft=@theme({color});bgc-{color,black}-100;brc-transparent
  --alias-outline=@theme({color});bgc-transparent;brc-{color,black}-200;@ihover(bgc-{color,black}-100);@ihover(c-{color,black}-600)

  --alias-btn=@{variant,solid}({color,black});fxrow-cc;px-4;py-1.5;rad-2
">
  <head>
    <!-- Include Maple in the head -->
    <script src="https://cdn.jsdelivr.net/npm/@f12io/maple/dist/maple.js"></script>
  </head>
  <body class="fxcol-cc g-4">
    <!-- Usage: Instant, dynamic component variations -->
    <button class="@btn">Primary (Solid Accent)</button>
    <button class="@btn(variant:soft,color:red)">Red (Soft)</button>
    <button class="@btn(variant:outline,color:green)">Green (Outline)</button>
    
    <!-- Or, you can use variants individually -->
    <button class="@btn @soft(blue)">Blue (Soft)</button>
    <button class="@btn @outline(orange)">Orange (Outline)</button>
  </body>
</html>

In this example, the @btn alias accepts variant and color parameters. Notice the powerful syntax @{variant,solid}({color,accent}): it dynamically resolves the alias name itself (e.g., to @soft or @outline) and forwards the color parameter into it. This allows you to create robust component APIs purely with utility classes, bridging the gap between static CSS and component architecture.

Specificity and Merging

Because aliases expand before merge checks, later classes override earlier alias members as expected:


<html class="--alias-focus-ring=olw-2px;olst=solid;olc=currentColor">
  <button class="@focus-ring olw-4px"></button>
  <!-- before merge: olw-2px olst=solid olc=currentColor olw-4px -->
  <!-- after merge: @focus-ring olw-4px -->
</html>

Maple keeps the alias class when at least one expanded utility inside the alias still applies. In this example, olw-4px overrides the alias's olw-2px, but the alias is kept because its outline style and color utilities still apply.

Alias-generated selectors are intentionally low-specificity. This lets a direct utility on the same element override an individual alias member even if the alias rule is generated later.

Alias Reference

The table below lists Maple’s core built-in alias classes. Larger alias families, such as flex layout and animation shortcuts, are documented in their own guide sections.

Alias

Expands To

abs

pos=absolute

fixed

pos=fixed

rel

pos=relative

sticky

pos=sticky

static

pos=static

iblock

d=inline-block

ifx

d=inline-flex

fx

d=flex

gr

d=grid

block

d=block

none

d=none

table

d=table

inline

d=inline

hidden

v=hidden

visible

v=visible

br

brw-px;brst=solid

brt

brtw-px;brtst=solid

brr

brrw-px;brrst=solid

brb

brbw-px;brbst=solid

brl

brlw-px;brlst=solid

brx

borderInlineWidth-px;borderInlineStyle=solid

brxs

borderInlineStartWidth-px;borderInlineStartStyle=solid

brxe

borderInlineEndWidth-px;borderInlineEndStyle=solid

bry

borderBlockWidth-px;borderBlockStyle=solid

brys

borderBlockStartWidth-px;borderBlockStartStyle=solid

brye

borderBlockEndWidth-px;borderBlockEndStyle=solid

cnt

cnt=inline-size

antialiased

-webkitFontSmoothing=antialiased;-mozOsxFontSmoothing=grayscale

truncate

of=hidden;tof=ellipsis;ws=nowrap

pill

rad=calc(infinity_*_1px)

More Aliases

Animation (like fade-in) and flex layout (like fxrow-cc) aliases are documented in their respective sections: Animations and Flex Layout.

Pro Tip

Adding antialiased to the <body> element is a good practice for sharper, more consistent font rendering across browsers.