Update api.md (twbs#35486)

* Wording tweak * Tweak wording Co-authored-by: Patrick H. Lauke <[email protected]>
ija-wang · Dec 28, 2021 · 2c9ecd0 · 2c9ecd0
1 parent 33c7f9f
commit 2c9ecd0
Showing 1 changed file with 24 additions and 2 deletions.
diff --git a/site/content/docs/5.1/utilities/api.md b/site/content/docs/5.1/utilities/api.md
@@ -15,8 +15,8 @@ The `$utilities` map contains all our utilities and is later merged with your cu
 | Option | Type | Default&nbsp;value | Description |
 | --- | --- | --- | --- |
 | [`property`](#property) | **Required** | – | Name of the property, this can be a string or an array of strings (e.g., horizontal paddings or margins). |
-| [`values`](#values) | **Required** | – | List of values, or a map if you don't want the class name to be the same as the value. If `null` is used as map key, it isn't compiled. |
-| [`class`](#class) | Optional | null | Name of the generated class. If not provided and `property` is an array of strings, `class` will default to the first element of the `property` array. |
+| [`values`](#values) | **Required** | – | List of values, or a map if you don't want the class name to be the same as the value. If `null` is used as map key, `class` is not prepended to the class name. |
+| [`class`](#class) | Optional | null | Name of the generated class. If not provided and `property` is an array of strings, `class` will default to the first element of the `property` array. If not provided and `property` is a string, the `values` keys are used for the `class` names. |
 | [`css-var`](#css-variable-utilities) | Optional | `false` | Boolean to generate CSS variables instead of CSS rules. |
 | [`local-vars`](#local-css-variables) | Optional | null | Map of local CSS variables to generate in addition to the CSS rules. |
 | [`state`](#states) | Optional | null | List of pseudo-class variants (e.g., `:hover` or `:focus`) to generate. |
@@ -134,6 +134,28 @@ Output:
 .o-100 { opacity: 1 !important; }
 ```
 
+If `class: null`, generates classes for each of the `values` keys:
+
+```scss
+$utilities: (
+  "visibility": (
+    property: visibility,
+    class: null,
+    values: (
+      visible: visible,
+      invisible: hidden,
+    )
+  )
+);
+```
+
+Output:
+
+```css
+.visible { visibility: visible !important; }
+.invisible { visibility: hidden !important; }
+```
+
 ### CSS variable utilities
 
 Set the `css-var` boolean option to `true` and the API will generate local CSS variables for the given selector instead of the usual `property: value` rules. Consider our `.text-opacity-*` utilities: