Home

Awesome

ngx-float-ui

npm npm MIT licensed Build state Size Rate this package

ngx-float-ui is an angular wrapper for the FloatingUI 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:
$ npm install @floating-ui/dom ngx-float-ui --save

Or

 $ yarn add @floating-ui/dom --save
 $ yarn add ngx-float-ui --save 
  1. You simply add into your module NgxFloatUiModule:
import {NgxFloatUiModule} from 'ngx-float-ui';

@NgModule({
 // ...
 imports: [
   // ...
   NgxFloatUiModule
 ]
})

Optionally you can include in your styles.css / styles.css one of the prebuilt themes:

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);
}
  1. Add to view:
 <float-ui-content #popper1Content>
     <p class="bold">Popper on bottom</p>
 </float-ui-content>
 <div [floatUi]="popper1Content"
      [showOnStart]="true"
      [showTrigger]="'click'"
  	hideOnClickOutside
      [hideOnScroll]="true"
      [placement]="'bottom'">
     <p class="bold">Hey!</p>
     <p class="thin">Choose where to put your popper!</p>         
 </div>
  1. As text:
     <div floatUi="As text"
          [showTrigger]="'hover'"
          [placement]="'bottom'"
          (onShown)="onShown($event)">
       <p class="bold">Pop</p>
       <p class="thin">on the bottom</p>
     </div>
     <div floatUi="{{someTextProperty}}"
          [showTrigger]="'hover'"
          [placement]="'bottom'"
          [styles]="{'background-color: 'blue''}"
          (onShown)="onShown($event)">
       <p class="bold">Pop</p>
       <p class="thin">on the bottom</p>
     </div>
  1. Position fixed, breaking overflow:
     <div floatUi="As text"
          [showTrigger]="'hover'"
          [placement]="'bottom'"
          [positionFixed]="true"
          (onShown)="onShown($event)">
     </div>
  1. Specific target:
<div class="example">
     <div #popperTargetElement></div>
     <div floatUi="As text"
          showTrigger="hover"
          placement="bottom"
          [targetElement]="popperTargetElement.nativeElement"
          (onShown)="onShown($event)">
     </div>
  1. hide/show programmatically:
 <div [floatUi]="tooltipcontent"
      showTrigger="hover"
      placement="bottom"
      [applyClass]="'popperSpecialStyle'">
      <p class="bold">Pop</p>
      <p class="thin">on the bottom</p>
    </div>
    <float-ui-content #tooltipcontent>
      <div>
        <p>This is a tooltip with text</p>
        <span (click)="tooltipcontent.hide()">Close</span>
      </div>
    </float-ui-content>
  1. Attributes map:

    OptionTypeDefaultDescription
    disableAnimationbooleanfalseDisable the default animation on show/hide
    disableStylebooleanfalseDisable the default styling
    disabledbooleanfalseDisable the popper, ignore all events
    showDelaynumber0Delay time until popper it shown
    hideTimeoutnumber0Set delay before the popper is hidden
    timeoutAfterShownumber0Set a time on which the popper will be hidden after it is shown
    placementPlacement(string)autoThe placement to show the popper relative to the reference element *
    targetElementHtmlElementautoSpecify a different reference element other the the one hosting the directive
    boundariesstring(selector)undefinedSpecify a selector to serve as the boundaries of the element
    showOnStartbooleanfalsePopper default to show
    showTriggerTrigger(string)clickTrigger/Event on which to show/hide the popper
    positionFixedbooleanfalseSet the popper element to use position: fixed
    appendTostringundefinedappend The popper-floatUi element to a given selector, if multiple will apply to first
    preventOverflowbooleanundefinedPrevent the popper from being positioned outside the boundary *
    hideOnClickOutsidebooleantruePopper will hide on a click outside
    hideOnScrollbooleanfalsePopper will hide on scroll
    hideOnMouseLeavebooleanfalsePopper will hide on mouse leave
    applyClassstringundefinedlist of comma separated class to apply on ngpx__container
    stylesObjectundefinedApply the styles object, aligned with ngStyles
    applyArrowClassstringundefinedlist of comma separated class to apply on ngpx__arrow
    onShownEventEmitter<>$eventEvent handler when popper is shown
    onHiddenEventEmitter<>$eventEvent handler when popper is hidden
    onUpdateEventEmitter<>$eventEvent handler when popper is updated
    ariaDescribeBystringundefinedDefine value for aria-describeby attribute
    ariaRolestringpopperDefine 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

  1. 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.

NgModule({
    imports: [
        BrowserModule,
        FormsModule,
        NgxFloatUiModule.forRoot({placement: NgxFloatUiPlacements.TOP})],
    declarations: [AppComponent],
    providers: [],
    bootstrap: [AppComponent]

});
OptionsTypeDefault
showDelaynumber0
disableAnimationbooleanfalse
disableDefaultStylingbooleanfalse
placementNgxFloatUiPopPlacements (string)auto
boundariesElementstring(selector)undefined
showTriggerNgxFloatUiTriggers (string)hover
positionFixedbooleanfalse
hideOnClickOutsidebooleantrue
hideOnMouseLeavebooleanfalse
hideOnScrollbooleanfalse
applyClassstringundefined
stylesObjectundefined
applyArrowClassstringundefined
ariaDescribeBystringundefined
ariaRolestringundefined
appendTostringundefined
preventOverflowbooleanundefined
  1. 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'

  1. 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

<a href="https://tonysamperi.github.io/ngx-float-ui/">Demo of ngx-float-ui</a>

Contribute

You can only report bugs. Every other issue will be deleted right away.

  $ 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! 🎉

jetbrains-logo

License

This project is licensed under the MIT License - see the LICENSE file for details

Thanks to

The developers of Floating UI