CSS @property: 사용자 지정 속성 등록

CSS @property @규칙은 CSS Houdini API의 일부로서, CSS 사용자 지정 속성의 자료형 검사, 제약 설정, 기본 값 설정, 상속 여부 등을 개발자가 직접 지정할 때 사용합니다.

@property 규칙을 쓰면 JavaScript 코드 없이도 사용자 지정 속성을 스타일시트 내에서 바로 등록할 수 있습니다. 유효한 @property 규칙은 JavaScript의 registerProperty()를 호출한 결과와 유사합니다.

구문

@property --rotation {
  inherits: false;
  initial-value: 45deg;
  syntax: "<angle>";
}

사용자 지정 속성의 이름은 <dashed-ident>로, -- 뒤에 사용자가 정의하는 이름을 붙입니다. 이름은 대소문자를 구분합니다.

서술자

inherits

규칙이 정의하는 사용자 지정 속성이 상속 대상인지를 제어하는 불리언 값입니다.

initial-value

속성의 초기 값을 정의합니다.

syntax

사용자 지정 속성에 사용할 수 있는 값을 설명하는 문자열입니다. 자료형 이름(<color>, <length>, <number> 등), 배수(+, #), 조합자(|), 사용자 지정 식별자를 사용할 수 있습니다. syntax 서술자 페이지에서 더 자세히 알아보세요.

설명

@property 규칙이 유효하려면 다음 규칙을 모두 만족해야 합니다.

• inherits와 syntax 서술자 모두 정의되어 있어야 합니다. 하나라도 없으면 해당 @property 규칙은 유효하지 않으며 무시됩니다.
• syntax 서술자가 보편 구문을 정의 (즉, syntax: '*') 하는 경우에는 initial-value 서술자를 생략할 수 있습니다. 그 외의 경우 initial-value 서술자도 필수로 정의해야 하며, 그렇지 않으면 해당 @property 규칙은 유효하지 않으며 무시됩니다.
• syntax 서술자가 보편 구문을 정의하지 않는 경우, initial-value 서술자는 반드시 독립적인 계산이 가능한 값이어야 합니다. 독립적인 계산이 가능한 값이란 다른 값에 의존하지 않고 계산 값으로 변환 가능한 값을 의미합니다. 예를 들어, 10px은 계산 값으로 변환 시 바뀌지 않으므로 독립적입니다. 1in = 96px이므로 2in도 독립적입니다. 하지만 1em은 부모의 font-size에 의존하므로 3em은 독립적이지 않습니다.
• inherits, initial-value, syntax 외의 알 수 없는 서술자는 정의해도 유효하지 않으므로 무시하지만, @property 규칙이 무효화되진 않습니다.

예제

사용자 지정 속성 등록하기

이 예제는 요소의 크기와 배경색을 각각 --item-size, --item-color 사용자 지정 속성으로 정의하는 모습을 보입니다.

아래 CSS 코드는 @property 규칙을 사용해서 <percentage>만 허용하고, 기본 값이 40%고, 부모의 값을 상속하는 --item-size 속성을 정의합니다.

@property --item-size {
  inherits: true;
  initial-value: 40%;
  syntax: '<percentage>';
}

그리고 다음 코드는 <color>만 허용하고, 기본 값은 aqua고, 부모의 값을 상속하지 않는 --item-color 속성을 정의합니다.

@property --item-color {
  inherits: false;
  initial-value: aqua;
  syntax: '<color>';
}

이제 이 두 사용자 지정 속성을 사용해 스타일을 적용할 수 있습니다.

@property --item-size {
  inherits: true;
  initial-value: 40%;
  syntax: '<percentage>';
}

@property --item-color {
  inherits: false;
  initial-value: aqua;
  syntax: '<color>';
}

#parent {
  border: 1px dashed black;
  display: flex;
  height: 200px;

  /* 부모에서 정한 값 */
  --item-color: green;
  --item-size: 20%;
}

.item {
  flex-grow: 1;

  /* 사용자 지정 속성을 스타일에 적용 */
  background-color: var(--item-color);
  height: var(--item-size);
}

/* 자식에 직접 정한 값들 */
.item:nth-child(2) {
  --item-color: orange;
  --item-size: 50%;
}
.item:nth-child(3) {
  /* 유효하지 않은 값들 */
  --item-color: 000;
  --item-size: 1000px;
}

<div id="parent">
  <div class="item">1 (상속만)</div>
  <div class="item">2 (직접 정의)</div>
  <div class="item">3 (직접, 무효한 값)</div>
</div>

부모에는 --item-color를 green, --item-size를 20%로 정의했습니다.

1번 아이템에는 크기와 색 모두 정의하지 않았습니다. --item-color는 상속 대상이 아니므로 green 대신 속성의 기본 값인 aqua가 적용됐고, --item-size는 상속 대상이므로 부모 높이의 20%에 해당하는 크기로 설정된 걸 확인할 수 있습니다.

2번 아이템에는 크기와 색을 모두 정의했습니다. 따라서 아이템에 정의한 orange 색과 50% 높이 모두 볼 수 있습니다.

3번 아이템에도 크기와 색을 모두 정의했지만, 두 속성 모두 syntax 서술자와 맞지 않는 값을 지정했습니다. 특히 --item-size의 1000px은 <length>로서는 유효하지만, --item-size는 <percentage> 구문만 허용하므로 유효하지 않은 값입니다. 그 결과 1번 아이템과 같이, 상속 대상이 아닌 배경색은 기본 값 aqua, 상속 대상인 높이는 부모에 지정한 값인 20%가 적용된 모습입니다.

명세

CSS Properties and Values API Level 1

브라우저 호환성