@external

The @external directive lets you augment the styles of another block in the context of the current one. It is declared inside a @block.

Unlike extends (inheritance — the child block absorbs the parent's styles into itself), @external inherits nothing: it changes the appearance of an external block only where it is nested inside the current one. For example, a button inside Toolbar gets a special style without affecting buttons elsewhere.

Syntax

@import { SomeBlock } from "./SomeBlock.ecss";

@block Parent {
  @external SomeBlock {
    /* additional styles for SomeBlock inside Parent */
  }

  @external SomeBlock.Element {
    /* styles for an element of SomeBlock inside Parent */
  }
}

The block referenced by @external must be imported via @import.

Parameters

Inside @external, the current block's parameters are available. The external block's parameters are not:

@block Panel {
  @param --compact boolean;

  @external NavLink {
    @if (--compact) {
      padding: 4px 8px;
    }
  }
}

Elements of the external block

Elements of the external block are accessed via a dot:

@external NavLink.Icon {
  width: 16px;
  height: 16px;
}

@external NavLink.Label {
  font-size: 13px;
}

Referencing the current block

@external can also reference the block it is declared in. This produces a descendant selector .Block .Block — the styles apply to the block nested inside another instance of itself (for example, a card inside a card):

@block Card {
  padding: 16px;

  @external Card {
    margin-top: 8px; /* .Card .Card */
  }
}

TIP

To style adjacent instances of the same block, plain CSS nesting with & is simpler: & + & { margin-left: 8px; } yields .Button + .Button — the gap between consecutive buttons.

Example

// Notification.ecss
@import { Button } from "./Button.ecss";

@enum Tone {
  values: "info", "success", "error";
}

@block Notification {
  @param --tone Tone;

  display: flex;
  align-items: flex-start;
  gap: 12px;
  padding: 16px;
  border-radius: 8px;

  @if (--tone == "success") {
    background: #f0fff4;
    color: #276749;
  }

  @if (--tone == "error") {
    background: #fff5f5;
    color: #9b2c2c;
  }

  @external Button {
    font-size: 13px;

    @if (--tone == "success") {
      color: #276749;
    }

    @if (--tone == "error") {
      color: #9b2c2c;
    }
  }

  @external Button.Text {
    font-weight: 500;
  }
}

See also

• @import — importing a block for use in @external
• @block — the block inside which @external is declared
• @element — block elements