@param

The @param directive declares a parameter inside a @block. Parameters control which CSS rules are applied to the component.

Syntax

@param --name Type;
@param --name? Type;
@param --name? Type: default;

@param is declared at the start of a @block body.

Parameter name

A parameter name is a CSS custom property (--name). In JS it is converted to camelCase:

ECSS	JS
--variant	variant
--is-disabled	isDisabled
--bg-color	bgColor

Required and optional

A parameter without ? is required: it must be passed on every call.

@param --variant Variant;
@param --size unit;

A ? after the name makes the parameter optional. If no value is passed, null is used (or an explicit default):

@param --label? string;
@param --label? string: "Submit";

INFO

A default value can be set only for an optional parameter.

Parameter type

All supported types are described in the data types reference. The type is always specified explicitly.

boolean

@param --disabled boolean;
@param --elevated? boolean: true;

In TypeScript: boolean.

string

@param --label? string: "Submit";
@param --href string;

In TypeScript: string.

number

@param --columns number;
@param --opacity? number: 1;

In TypeScript: number.

unit

@param --size unit;
@param --gap? unit: 8px;

In TypeScript: a string literal of the form "16px", "1.5rem" — a number with a valid unit.

color

@param --bg color;
@param --accent? color: #646cff;

In TypeScript: string.

Reference to @enum

The parameter accepts one of the enum's values. The type is the @enum name:

@enum Variant {
  values: "primary", "danger", "ghost";
}

@block Button {
  @param --variant Variant;
}

In TypeScript: a union type of the enum's values.

Default value

A default is specified with : and is used when the parameter is not passed. It requires ?:

@param --variant? Variant: "primary";
@param --disabled? boolean: false;
@param --size? unit: 16px;

An optional parameter without an explicit default gets null by default.

TypeScript types

Syntax	TypeScript type	Default
@param --p Type;	Type	—
@param --p? Type;	Type | null | undefined	null
@param --p? Type: value;	Type | null | undefined	value

Usage

Parameters can be used in @if conditions and as CSS property values:

@block Badge {
  @param --status Status;
  @param --outlined? boolean: false;
  @param --gap? unit: 8px;

  padding: 8px 16px;
  column-gap: --gap; // no var() needed

  @if (--outlined) {
    border: 1px solid currentColor;
  }

  @if (--status == "error") {
    background: #ffe0e0;
    color: #cc0000;
  }
}

Constraints

• @param is declared only inside a @block, not inside @element
• Parameter names are unique within a block and all its descendants — a child block cannot declare a parameter with a name that already exists on the parent

See also

• Data types — full type reference
• @enum — declaring enum types
• @if — using parameters in conditions
• Core API: blocks — passing parameters at the call site