# useRole

Adds base screen reader props to the reference and floating
elements for a given `role{:.objectKey}`.

```js
import {useRole} from '@floating-ui/react';
```

## Usage

This hook is an interaction hook that returns ARIA attribute
props.

To use it, pass it the `context{:.const}` object returned from
`useFloating(){:js}`, and then feed its result into the
`useInteractions(){:js}` array. The returned prop getters are
then spread onto the elements for rendering.

```js {4-8} /context/
function App() {
  const {refs, floatingStyles, context} = useFloating();

  const role = useRole(context);

  const {getReferenceProps, getFloatingProps} = useInteractions([
    role,
  ]);

  return (
    <>
      <div ref={refs.setReference} {...getReferenceProps()}>
        Reference element
      </div>
      <div
        ref={refs.setFloating}
        style={floatingStyles}
        {...getFloatingProps()}
      >
        Floating element
      </div>
    </>
  );
}
```

## Props

```ts
interface Props {
  enabled?: boolean;
  role?:
    | 'dialog'
    | 'alertdialog'
    | 'tooltip'
    | 'menu'
    | 'listbox'
    | 'grid'
    | 'tree';
}
```

### enabled

default: `true{:js}`

Conditionally enable/disable the hook.

```js
useRole(context, {
  enabled: false,
});
```

### role

default: `'dialog'{:js}`

The role of the floating element.

```js
useRole(context, {
  role: 'tooltip',
});
```

#### Item roles

As only the reference and floating element receives these props,
you'll need to provide roles for the items inside the floating
element if required.

For instance:

- A `'menu'{:js}` role will require the focusable children to
  have a role of `'menuitem'{:js}`, `'menuitemcheckbox'{:js}`, or
  `'menuitemradio'{:js}`.
- A `'listbox'{:js}` role will require the focusable children to
  have a role of `'option'{:js}`. If inside a group, then wrapped
  inside a `'group'{:js}` role that is
  `aria-labelledby{:.keyword}` the group heading.

It's recommended that you read
[WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.2/)
to ensure your item elements have semantic roles and attributes.
