diff --git a/README.md b/README.md index fb8843d6..09ebd43f 100644 --- a/README.md +++ b/README.md @@ -114,17 +114,35 @@ The addon provides 1 Glimmer component and 3 helpers:
<ContainerQuery> -The component uses `...attributes` so that you can pass `class` or [`local-class`](https://github.com/salsify/ember-css-modules) _for styling_.1 +### Arguments -It also accepts these arguments: +You can pass these arguments to the component. | Name | Required | Description | Type | |--|:--:|--|--| -| @features | Yes2 | Container query definitions | POJO | +| @features | Yes1 | Container query definitions | POJO | | @dataAttributePrefix | No | Prefix for data attributes | string | | @debounce | No | Debounce time for resize (ms) | number ≥ 0 | +| @tagName | No | Container tag name2 | HTML tag name | -The component returns a few values that you can consume: +1. The component renders without error when `@features` isn't provided. In practice, you will always want to set `@features`. + +2. By default, the component is a `
` element. You can pass a valid HTML tag name to facilitate accessibility and semantic HTML. + +### Attributes + +You _may_1 pass attributes to the component for these reasons: + +- Style (e.g. `class`, [`local-class`](https://github.com/salsify/ember-css-modules)) +- Accessibility (e.g. ARIA attributes2, roles) + +1. Do refrain from overusing splattributes (e.g. pass a `{{did-insert}}` modifier to fetch data), since the component's API may change and cause unexpected results. Practice separation of concerns when possible. For example, data fetching can be handled by another element or [`@use` decorator](https://github.com/emberjs/rfcs/blob/use-and-resources/text/0567-use-and-resources.md). + +2. When an [ARIA attribute has multiple values](https://github.com/ijlee2/ember-container-query/issues/38#issuecomment-647017665), the order of values can matter. At the moment, splattributes doesn't guarantee the order. + +### Outputs + +You can consume these values in your app or addon. | Name | Yielded | Description | Type | |--|:--:|--|--| @@ -132,16 +150,14 @@ The component returns a few values that you can consume: | dimensions | Yes | Container dimensions | POJO | | data-container-query-_{featureName}_ | No | Data attributes for CSS selector | HTML data attribute | -1. Do refrain from overusing splattributes (e.g. pass a `{{did-insert}}` modifier to fetch data), since the component's API may change and cause unexpected results. Practice separation of concerns when possible. For example, data fetching can be handled by another element or [`@use` decorator](https://github.com/emberjs/rfcs/blob/use-and-resources/text/0567-use-and-resources.md). - -2. The component renders without error when `@features` isn't provided. In practice, you will always want to set `@features`. -
{{cq-aspect-ratio}}, {{cq-height}}, {{cq-width}} +### Arguments + All helpers accept these arguments: | Name | Required | Description | Type |