【CSS Modules】additive-symbolsアットルール記述子の使い方

additive-symbolsアットルール記述子の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月29日更新日: 2026年03月28日

基本的な使い方

additive-symbolsプロパティは、CSSの@counter-styleアットルール内で使用され、カスタムカウンターの加算式記号を定義するために必要な値を保持するプロパティです。このプロパティは、ウェブページでリストの番号付けや記号表示を、標準のスタイル設定を超えて独自にカスタマイズしたい場合に利用されます。

具体的には、additive-symbolsは「記号（シンボル）」とその記号が表す「重み（数値）」のペアを複数指定します。例えば、ローマ数字の「I」が1、「V」が5、「X」が10といったように、特定の数値に対応するシンボルを割り当てることができます。このプロパティの核心は、これらのシンボルを組み合わせて、指定されたカウンター値を表現する「加算式」の番号付けシステムを構築する点にあります。ブラウザはリストのカウンター値に対し、最も大きな重みを持つシンボルから順に適用できるものを選択し、そのシンボルを追加して残りの値を処理することで、最終的な記号列を生成します。例えば、数値が8の場合、重みが5の「V」と、重みが1の「I」を3つ組み合わせて「VIII」と表示されるような仕組みです。

システムエンジニアを目指す初心者の方にとって、このプロパティは、特定の文化圏に合わせたリストマーカーや、論文・資料などの特殊なセクション番号付け、あるいはゲームのスコア表示など、標準のリストスタイルでは実現できない複雑な表示要件を満たす際に非常に有用です。@counter-styleアットルールにおける重要な記述子であり、多様なデザインや国際化に対応するウェブコンテンツ開発において、柔軟な表現力を提供します。

公式リファレンス: additive-symbols

構文(syntax)


1additive-symbols: <integer> <symbol> [, <integer> <symbol>]*;

引数(parameters)

引数なし

引数はありません

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

CSSでカスタムカウンターを定義する


1/*
2 * additive-symbols は、カスタムのカウンターシステムを定義する `@counter-style` アットルール内で使用されます。
3 * 特に、ローマ数字のように複数のシンボルを組み合わせて数を表現する「加算システム」を構築する際に役立ちます。
4 *
5 * この例では、標準的なローマ数字のカウンターシステムを定義します。
6 * 定義されたカウンターは、HTMLのリストアイテム (<li>) などに適用できます。
7 */
8@counter-style roman-numerals {
9  /*
10   * system: additive は、additive-symbols プロパティを使用するために必須です。
11   * これにより、数値が複数のシンボルの加算として表現されることを指定します。
12   */
13  system: additive;
14
15  /*
16   * additive-symbols は、数値とそれに対応するシンボルのペアを定義します。
17   * 大きい値から小さい値の順に記述するのが一般的で、アルゴリズムの効率を高めます。
18   * 例: 1000 'M' は、数値1000をシンボル 'M' で表すことを意味します。
19   * 各ペアはカンマで区切ります。
20   */
21  additive-symbols:
22    1000 'M',
23    900 'CM',
24    500 'D',
25    400 'CD',
26    100 'C',
27    90 'XC',
28    50 'L',
29    40 'XL',
30    10 'X',
31    9 'IX',
32    5 'V',
33    4 'IV',
34    1 'I';
35
36  /*
37   * fallback は、定義された additive-symbols の範囲外の数値（例えば負の数や極端に大きな数）
38   * が現れた場合に、どの既存のカウンターシステムにフォールバックするかを指定します。
39   * ここでは、一般的なアラビア数字 (1, 2, 3...) を使用する `decimal` をフォールバックとしています。
40   */
41  fallback: decimal;
42
43  /*
44   * negative-sign は、負の数値を表現する際に、カウンターの先頭に追加されるシンボルを定義します。
45   * 例えば、-1 を表現する際にこの記号が使われます。
46   */
47  negative-sign: '-';
48
49  /*
50   * suffix は、各カウンターシンボルの直後に追加されるシンボルを定義します。
51   * ここでは、リストアイテムの後に通常付くピリオドを付けています。
52   */
53  suffix: '.';
54}

CSSのadditive-symbolsは、@counter-styleアットルール内で使用されるディスクリプタです。これは、HTMLのリストなどで使われる標準の番号付け（カウンター）システムだけでなく、独自のカスタムカウンターシステムを定義するために利用されます。

特に、ローマ数字のように、複数のシンボルを組み合わせて数を表現する「加算システム」を構築する際に重要な役割を果たします。additive-symbolsプロパティは、数値とそれに対応するシンボルのペアを定義します。例えば、「1000はM」「900はCM」といった具体的な対応付けを記述します。これらのペアはカンマで区切り、効率的な処理のため、通常は大きい値から小さい値の順に定義されます。このプロパティを使用するには、必ずsystem: additiveというプロパティも同時に指定する必要があります。

additive-symbolsプロパティ自体には引数はなく、戻り値もありません。代わりに、数値とシンボルのペアのリストを値として受け取ります。

また、@counter-styleアットルール内では、additive-symbolsの他にも、いくつかの関連プロパティを定義できます。例えば、fallbackは定義されたカウンターシステムの範囲外の数値が出た場合に、どの既存システムに切り替えるかを指定します。negative-signは負の数を表現する際の記号を定義し、suffixは各カウンターシンボルの直後に追加される文字を定義します。これにより、非常に柔軟なカスタムカウンターシステムを構築することが可能です。

additive-symbolsプロパティを使用する際は、必ずsystem: additiveプロパティを指定してください。これを省略すると、定義したカスタムカウンターが期待通りに動作しません。数値とシンボルのペアは「数値 'シンボル'」の形式で記述し、大きい値から小さい値の順に並べることが、処理効率を最適化するために推奨されます。また、定義した数値範囲外のカウンターが表示される場合に備え、fallbackプロパティで適切な代替のカウンターシステムを指定することで、予期せぬ表示崩れを防ぎ、より堅牢なシステムを構築できます。このカウンターは@counter-style内で定義されるものであり、実際にHTML要素に適用するにはlist-style-typeプロパティなどで明示的に参照する必要がある点にご注意ください。