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.

Reactivity

Aliases are not reactive. If you change an alias definition on <html> after elements using that alias have already been processed, Maple does not automatically revisit those existing alias usages. Treat aliases as root-level configuration for reusable utility shortcuts. For live changes, use CSS variables instead.

Pro Tip

Aliases work best when they follow utility-first logic: multiple declarations doing one clear job, like antialiased or truncate. Avoid using aliases as component-sized CSS classes for buttons, cards, or panels; extract those patterns into components or templates instead.

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.

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

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.