> For the complete documentation index, see [llms.txt](https://apcom.gitbook.io/altrone-ui/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apcom.gitbook.io/altrone-ui/components/containers/floatingbox.md).

# FloatingBox

FloatingBox is a great and convenient way to create a dropdown on the page. It requires an element around which positioning will occur. 

{% hint style="info" %}
To control the visibility of the FloatingBox you have to use conditional rendering. When FloatingBox is exist on the page - it visible. You should provide closing logic in **`onClose`** callback. 
{% endhint %}

```tsx
import { FloatingBox, Button, Paragraph } from 'altrone-ui';

const [visible, setVisible] = useState(false);
const buttonRef = useRef<HTMLButtonElement>();

return <div>
    <Button ref={buttonRef} onClick={() => setVisible(true)}>Show</Button>
    {visible && <FloatingBox 
        targetElement={buttonRef.current} 
        onClose={() => setVisible(false);}
    >
        <Paragraph>Popup content</Paragraph>
    </FloatingBox>}
</div>;
```

## Under the hood

Altrone uses **`popper.js`** dependency to place a popup on the page.&#x20;

By default, we use 'auto' placement for any FloatingBox component. But you can change this via placement property. Also Altrone uses some modificators for the popup, like offset, sameWidth, preventOverflow and beforeWrite. You cannot add any other popper modificators to FloatingBox.&#x20;

But you can use some custom popper settings via popperProps property. [Read Popper.js documentation](https://popper.js.org/) to get more information about this. &#x20;

## Closing a popup

By default, each FloatingBox closes when the user clicks outside the FloatingBox. But, there are some properties to change this behaviour.

Property `closeOnAnotherFloatingBoxClick` allows to disable closing when user clicks on another FloatingBox. This is useful when you have FloatingBoxes inside of your FloatingBox (for instance, when you use [Select](/altrone-ui/components/forms/select.md) or [DatePicker](/altrone-ui/components/forms/datepicker.md)).

For more complicated cases you can use `preventClose` props. When you have FloatingBox on the page it listens all user clicks. When user clicks somewhere, FloatingBox trigger `preventClose` function. If user clicked outside the FloatingBox but `preventClose` function returned `true` the popup won't be closed. &#x20;

## Mobile devices

There are two ways how to display FloatingBox on mobile devices: `default` and as `modal`. Use values from [`FloatingBoxMobileBehaviour`](#floatingboxmobilebehaviour) enum to set `mobileBehaviour` property.

When variant is `default`, the popup on mobile devices looks exactly the same as on desktop. But when you choose `modal` it will be rendered as [Modal](/altrone-ui/components/containers/modal.md). &#x20;

{% hint style="info" %}
Some popups on mobile devices will be more convenient in a display format as modal than popup. Don't forget to set this property for some FloatingBox.
{% endhint %}

### <mark style="color:blue;">FloatingBoxMobileBehaviour</mark>

```typescript
enum FloatingBoxMobileBehaviour {
  default = 'default',
  modal = 'modal'
}
```

## Altrone Options

In **Altrone 2.2** FloatingBox got a new configuration options ([read more](#altrone-options)). To achieve this, you can leverage `floatingBox.offset`  and `floatingBox.windowOffset` to set offset between this floating box and parent element or window.

## Properties

| Property                                                   | Type                                                        | Description                                                                                                                                                                                               |
| ---------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`targetElement`**<mark style="color:red;">**`*`**</mark> | `HTMLElement`                                               | The DOM element around which positioning will occur.                                                                                                                                                      |
| **`onClose`**<mark style="color:red;">**`*`**</mark>       | `() => void`                                                | Callback fires when FloatingBox is ready to close                                                                                                                                                         |
| **`offset`**                                               | `number`                                                    | Space (in px) between the target element and the popup. Default value is `4`                                                                                                                              |
| **`placement`**                                            | `PopperOptions['placement']`                                | Side of placement. Default value is `auto`                                                                                                                                                                |
| **`popperProps`**                                          | `Omit<Partial<PopperOptions, 'modifiers'>>`                 | <p>Extra parameters for popper.js<br><br> <em><mark style="color:red;background-color:red;"><strong>Deprecated</strong></mark></em> . <em>Will be removed in 3.0</em></p>                                 |
| **`useParentWidth`**                                       | `boolean`                                                   | The popup has the same width as the target element. Default value is `false`                                                                                                                              |
| **`minWidth`**                                             | `number \| string`                                          | Minimum width of the popup. Works only with `useParentWidth` = `true` . Default value is `undefined`                                                                                                      |
| **`maxHeight`**                                            | `number \| string`                                          | Maximum height of the popup. Default value is `undefined`                                                                                                                                                 |
| **`useRootContainer`**                                     | `boolean`                                                   | If this is true then you popup will be placed in the root `.altrone` div. Default value is `false`                                                                                                        |
| **`preventClose`**                                         | `(e: MouseEvent) => boolean`                                | Via this prop you can prevent closing in some cases. Default value is `undefined`                                                                                                                         |
| **`mobileBehaviour`**                                      | [`FloatingBoxMobileBehaviour`](#floatingboxmobilebehaviour) | Control the appearance of the popup on mobile devices. Default value is `default`                                                                                                                         |
| **`closeOnAnotherFloatingBoxClick`**                       | `boolean`                                                   | If this is true, then when you click on another popup  other popup won't be closed. This is useful for cases when you have selects or any other FloatingBoxes inside your popup. Default value is `false` |
| **`surface`**                                              | `Surface`                                                   | <p>Surface of the popup. Default value is <code>glass</code>.</p><p></p><p>This property is available only in 2.0 and later</p>                                                                           |
| **`elevation`**                                            | `Elevation`                                                 | <p>Elevation of the popup. Default value is <code>floating</code>.</p><p></p><p>This property is available only in 2.0 and later</p>                                                                      |
| **`className`**                                            | `string`                                                    | Custom CSS class                                                                                                                                                                                          |

## History

* **`Altrone 2.2`**:
  * marked `popperProps` <mark style="color:red;">as deprecated</mark>. Will be removed in 3.0
  * added `offset` config prop
  * added `windowOffset` config prop
* **`Altrone 2.0`:**
  * added `surface` property
  * added `elevation` property
  * added offsets from window boundaries
* **`Altrone 1.0`:** initial release