diff --git a/docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx b/docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx index 3892c4851d..e0a984cd64 100644 --- a/docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx +++ b/docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx @@ -13,16 +13,18 @@ The Heading component has been designed with accessibility in mind. The component offers flexibility in terms of the HTML element used for the root node, the `role` attribute, and the `level` attribute. These properties allow for the creation of semantic and accessible headings. -| Name | Type | Description | -| :---- | :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------- | -| as | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "div"` | Defines the HTML element to be rendered. | -| role | `"heading"` | Can only be used if `as="div"`. If defined, sets the role of the element to be "heading". | -| level | `number` | Can only be used if `as="div"` and "`role="heading`". Defines the `aria-level` of the rendered `div` with the heading role. | +| Name | Type | Description | +| :---- | :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------- | +| as | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "div"` | Defines the HTML element to be rendered. | +| role | `"heading"` | Can only be used if `as="div"`. If defined, sets the role of the element to be "heading". | +| level | `number` | Must be used if `as="div"` and `role="heading"`. Defines the `aria-level` of the rendered `div` with the heading role. | All the props above are optional by default. -If they are not provided, the component will render a `div` element with no role or aria-level defined. -It is not semantically wrong but won't tell screen readers that the element is a heading. This should be used only for decorative purposes. +### Example 1 + +If the `as` prop is not provided, the component will render a `div` element. +In this case, no `role` or `level` are defined by default, and the component will render just a `div` element. ```jsx Hello World! @@ -34,8 +36,12 @@ renders:
Hello World!
``` -If the `as` prop is set to `"div"` (or undefined), the `role` prop is optional, but only accepts one possible value (if not `undefined`): `"heading"`. -If the `role` prop is set to `"heading"`, the `level` prop must be defined as well. It will tell assistive technologies the level of the heading. +It is not semantically wrong but won't tell screen readers that the element is a heading. This should be used only for decorative purposes. + +If the `as` prop is set to `"div"` (or undefined), it's possible to set the `role="heading` to indicate to assistive technologies that this element should be treated and formatted like a heading. +This is the only accepted value for the `role` prop. + +In addition, if the `role` prop is set to `"heading"`, the `level` prop **must** be defined as well. It will tell assistive technologies the level of the heading. The `level` prop must be a number between 1 and 6 and cannot be used if the `role` prop is not set to `"heading"`. ```jsx @@ -50,8 +56,10 @@ renders:
Hello World!
``` +### Example 2 + If the `as` prop is set to `"h1"`, `"h2"`, `"h3"`, `"h4"`, `"h5"`, or `"h6"`, the component will render the corresponding HTML element. -In that case, the `role` and `level` props are not needed, since assistive technologies will recognize the element as a heading and its correct level automatically. +In that case, the `role` and `level` props **cannot** be used, since assistive technologies will recognize the element as a heading and its correct level automatically. ```jsx Hello World!