Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tonysamperi/ngx-float-ui
Angular wrapper for floating-ui
https://github.com/tonysamperi/ngx-float-ui
Last synced: 3 months ago
JSON representation
Angular wrapper for floating-ui
- Host: GitHub
- URL: https://github.com/tonysamperi/ngx-float-ui
- Owner: tonysamperi
- License: mit
- Created: 2023-11-04T16:05:24.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-07-14T20:55:58.000Z (4 months ago)
- Last Synced: 2024-07-15T21:23:43.607Z (4 months ago)
- Language: TypeScript
- Homepage: https://tonysamperi.github.io/ngx-float-ui/
- Size: 792 KB
- Stars: 17
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
- awesome-angular - ngx-float-ui - Angular wrapper for the [Floating UI](https://floating-ui.com/) library. (Table of contents / Third Party Components)
- fucking-awesome-angular - ngx-float-ui - Angular wrapper for the 🌎 [Floating UI](floating-ui.com/) library. (Table of contents / Third Party Components)
README
# ngx-float-ui
[![npm][badge-npm-version]][url-npm] [![npm][badge-npm-downloads]][url-npm] [![MIT licensed][badge-licence]][url-licence] [![Build state][badge-ci-state]][url-ci-state] [![Size][badge-bundle]][url-bundle] [![Rate this package][badge-openbase]][url-openbase]
ngx-float-ui is an angular wrapper for the [FloatingUI](https://floating-ui.com/) library (v ^1.5.3).
## VERY IMPORTANT READ THIS
I'm moving this to the top because it appears that people don't get to reading it in the **contribute** section.
FOR THIS LIBRARY **PLEASE USE ISSUES ONLY FOR BUG REPORTING**. DON'T OPEN ISSUES SUCH AS "I need upgrade for Angular 1745646456" especially if Angular 1745646456 was released a few days ago.
I **guarantee** that I manage the updates **AS SOON AS POSSIBLE**. But as you understand this is not a paying job, so you can't get Angular 1745646456 the day it gets released.
**ISSUES NOT RESPECTING THIS WILL BE DELETED IMMEDIATELY WITHOUT ANY RESPONSE**.
Thank you.
### Premise
The goal of this library is to adopt the more promising technology of floating-ui instead of popper.js and make it available in our Angular projects.
### Installation
node and npm are required to run this package.
1. Use npm/yarn to install the package:
```terminal
$ npm install @floating-ui/dom ngx-float-ui --save
```
Or
```terminal
$ yarn add @floating-ui/dom --save
$ yarn add ngx-float-ui --save
```
2. You simply add into your module `NgxFloatUiModule`:
```typescript
import {NgxFloatUiModule} from 'ngx-float-ui';
@NgModule({
// ...
imports: [
// ...
NgxFloatUiModule
]
})
```
Optionally you can include in your `styles.css` / `styles.css` one of the prebuilt themes:
* `@import node_modules/ngx-float-ui/css/theme-dark.css`
* `@import node_modules/css/theme-white.css`
* `@use ngx-float-ui/scss/theme as floatUiBaseTheme`
* `@use ngx-float-ui/scss/theme-dark as floatUiDarkTheme`
* `@use ngx-float-ui/scss/theme-white floatUiWhiteTheme`
or easily create your own theme using the @mixin:
```
@use "ngx-float-ui/scss/theme" as floatUiBaseTheme;
body {
@include floatUiBaseTheme.ngx-float-ui-theme($background-color, $text-color, $max-width, $z-index);
}
```
3. Add to view:
```HTML
Popper on bottom
Hey!
Choose where to put your popper!
```
4. As text:
```HTML
Pop
on the bottom
```
```HTML
Pop
on the bottom
```
5. Position fixed, breaking overflow:
```HTML
```
6. Specific target:
```HTML
```
7. hide/show programmatically:
```HTML
Pop
on the bottom
This is a tooltip with text
Close
```
8. Attributes map:
| Option | Type | Default | Description |
|:-------------------|:---------------- |:--------- |:---------------------------------------------------------------------------------------|
| disableAnimation | boolean | false | Disable the default animation on show/hide |
| disableStyle | boolean | false | Disable the default styling |
| disabled | boolean | false | Disable the popper, ignore all events |
| showDelay | number | 0 | Delay time until popper it shown |
| hideTimeout | number | 0 | Set delay before the popper is hidden |
| timeoutAfterShow | number | 0 | Set a time on which the popper will be hidden after it is shown |
| placement | Placement(string) | auto | The placement to show the popper relative to the reference element * |
| targetElement | HtmlElement | auto | Specify a different reference element other the the one hosting the directive |
| boundaries | string(selector) | undefined | Specify a selector to serve as the boundaries of the element |
| showOnStart | boolean | false | Popper default to show |
| showTrigger | Trigger(string) | click | Trigger/Event on which to show/hide the popper |
| positionFixed | boolean | false | Set the popper element to use position: fixed |
| appendTo | string | undefined | append The popper-floatUi element to a given selector, if multiple will apply to first |
| preventOverflow | boolean | undefined | Prevent the popper from being positioned outside the boundary * |
| hideOnClickOutside | boolean | true | Popper will hide on a click outside |
| hideOnScroll | boolean | false | Popper will hide on scroll |
| hideOnMouseLeave | boolean | false | Popper will hide on mouse leave |
| applyClass | string | undefined | list of comma separated class to apply on ngpx__container |
| styles | Object | undefined | Apply the styles object, aligned with ngStyles |
| applyArrowClass | string | undefined | list of comma separated class to apply on ngpx__arrow |
| onShown | EventEmitter<> | $event | Event handler when popper is shown |
| onHidden | EventEmitter<> | $event | Event handler when popper is hidden |
| onUpdate | EventEmitter<> | $event | Event handler when popper is updated |
| ariaDescribeBy | string | undefined | Define value for aria-describeby attribute |
| ariaRole | string | popper | Define value for aria-role attribute |
\* **VERY IMPORTANT**: All the "auto" placements can't be used in combo with prevent overflow (as per float-ui specs), because the two algorythms **would conflict**, ending in infinite repositioning.
See [here](https://floating-ui.com/docs/autoPlacement#usage)
9. Override defaults:
ngx-float-ui comes with a few default properties you can override in default to effect all instances
These are overridden by any child attributes.
```JavaScript
NgModule({
imports: [
BrowserModule,
FormsModule,
NgxFloatUiModule.forRoot({placement: NgxFloatUiPlacements.TOP})],
declarations: [AppComponent],
providers: [],
bootstrap: [AppComponent]
});
```
| Options | Type | Default |
|:----------------------|:---------------------------------|:----------|
| showDelay | number | 0 |
| disableAnimation | boolean | false |
| disableDefaultStyling | boolean | false |
| placement | NgxFloatUiPopPlacements (string) | auto |
| boundariesElement | string(selector) | undefined |
| showTrigger | NgxFloatUiTriggers (string) | hover |
| positionFixed | boolean | false |
| hideOnClickOutside | boolean | true |
| hideOnMouseLeave | boolean | false |
| hideOnScroll | boolean | false |
| applyClass | string | undefined |
| styles | Object | undefined |
| applyArrowClass | string | undefined |
| ariaDescribeBy | string | undefined |
| ariaRole | string | undefined |
| appendTo | string | undefined |
| preventOverflow | boolean | undefined |
10. NgxFloatUiPopPlacements:
| 'top'
| 'bottom'
| 'left'
| 'right'
| 'top-start'
| 'bottom-start'
| 'left-start'
| 'right-start'
| 'top-end'
| 'bottom-end'
| 'left-end'
| 'right-end'
| 'auto'
| 'auto-start'
| 'auto-end'
11. NgxFloatUiTriggers:
| 'click'
| 'mousedown'
| 'hover'
| 'none'
### Liking hardcoded strings everywhere? Too lazy to use Enums? No problem mate!
`floatUiLoose` is what you're looking for!
You can then use `loosePlacement` and `looseTrigger` passing the values above as strings!
### Demo site with sample codes
Demo of ngx-float-ui
### Contribute
You can only **report bugs**. Every other issue will be deleted right away.
```terminal
$ npm install
$ npm run start //run example
```
## Special thanks
Jetbrains is now supporting this library with an open-source license, which will allow a better code! 🎉
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
### Thanks to
The developers of Floating UI
[badge-bundle]: https://img.shields.io/bundlephobia/minzip/ngx-float-ui
[badge-ci-state]: https://github.com/tonysamperi/ngx-float-ui/actions/workflows/main.yml/badge.svg
[badge-licence]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
[badge-npm-downloads]: https://img.shields.io/npm/dm/ngx-float-ui.svg?style=flat-square
[badge-npm-version]: https://img.shields.io/npm/v/ngx-float-ui.svg?style=flat-square
[badge-openbase]: https://badges.openbase.com/js/rating/ngx-float-ui.svg
[url-bundle]: https://img.shields.io/bundlephobia/minzip/ngx-float-ui
[url-ci-state]: https://github.com/tonysamperi/ngx-float-ui/actions
[url-licence]: https://github.com/tonysamperi/ngx-float-ui/blob/master/LICENSE
[url-npm]: https://www.npmjs.com/package/ngx-float-ui
[url-openbase]: https://openbase.com/js/ngx-float-ui