Provide simple, configurable, cubic-bezier support smooth scroll for Angular 7+
Javascript Browser APIs has scrollTo
and scrollIntoView
method. Which allow us to manipulate browser native scroll behavior easily.
But some browser does not supports behavior: 'smooth'
option. Thus, this methods doesn't have options for duration nor timing-function. And we have to seek for workaround to know when this behavior going to ends.
This package is configurable, compatible, support timing function(even cubic-bezier function) and use rxjs.Observable
to notify the subscribers when behavior ends.
npm install @eunsatio/ngx-smooth-scroll
Import
NgxSmoothScrollModule
into your module.
<div class="container" [ngxSmoothScroll]="options" childSelector=".content" smooth-wheel>
<!---->
<div class="content"></div>
<!---->
</div>
<div class="control-section" #controlSection>
<!-- The event will bind to this element -->
</div>
<div class="container" [ngxSmoothScroll]="options" childSelector=".content" [smooth-mouse]="controlSection">
<!---->
<div class="content"></div>
<!---->
</div>
public options: NgxSmoothScrollDirectiveOption = {
duration: 500, // Global option
wheel: {
duration: 600, // This will override global option
timingFunction: 'ease-out'
},
keydown: {
timingFunction: 'ease-in'
}
}
<div class="container" [ngxSmoothScroll]="options" childSelector=".content" smooth-wheel smooth-keydown>
<!---->
<div class="content"></div>
<!---->
</div>
Import and Inject
NgxSmoothScrollService
.
public scrollToTarget() {
this.smoothScrollService.scrollToElement(this.containerElRef.nativeElement, this.targetElRef.nativeElement, {
duration: 600,
timingFunction: 'ease-in-out'
});
}
Import
NgxSmoothScroll
.
ngAfterViewInit() {
this.smoothScroll = new NgxSmoothScroll(this.containerElRef.nativeElement);
}
public scrollToTarget() {
this.smoothScroll.scrollTo({ x: 0, y: 300 }, {
duration: 800,
timingFunction: '.13, 1.07, .51, 1.29'
});
}
-
ngxSmoothScroll:
NgxSmoothScrollDirectiveOption
optional
Scroll option object. Can specify options for each event. see more
-
childSelector:
string
optional
Child element selector.
- @default:
'.ngx-smooth-scroll-content'
- @default:
-
skip:
number
optional
Amount of index to skip on each event.
- @default:
0
- @default:
-
keyCode:
{ forward: number[]; reverse: number[] }
optional
Key code to define actions when
smooth-keydown
event enabled.- @default:
{ forward: [ 39, 40, 68, 83 ], reverse: [ 37, 38, 65, 87 ] }
- @default:
-
autoInterruption:
boolean
optional
experimental
Whether cancel current scroll animation on another
smooth-*
event.- @default:
false
- @default:
-
autoDetect:
boolean
optional
Whether detect current index automatically. If
false
, detect index only once.- @default:
true
- @default:
-
autoDetectDirection:
'mixed' | 'vertical' | 'horizontal'
optional
Axis to detect current index. If set this to
vertical
, can reduce unnecessary calculation invertical
only scroll.- @default:
'mixed'
- @default:
-
detectOffsetX:
number
optional
X offset to detect current index. If
0
, the first child element whthin container left boundary will be deteceted.- @default:
0.5
- @default:
-
detectOffsetY:
number
optional
Y offset to detect current index. If
0
, the first child element whthin container top boundary will be deteceted.- @default:
0.5
- @default:
-
actionDirection:
'mixed' | 'vertical' | 'horizontal'
optional
Axis to detect direction for
smooth-mouse
andsmooth-touch
.- @default:
'mixed'
- @default:
-
actionMinDistance:
number
optional
Minimum distance(px) to trigger scroll animation for
smooth-mouse
andsmooth-touch
.- @default:
30
- @default:
-
smooth-wheel:
boolean | any | any[]
optional
Whether enable wheel event or binding element(s).
- @default:
false
- @default:
-
smooth-keydown:
boolean | any | any[]
optional
Whether enable keydown event or binding element(s).
- @default:
false
- @default:
-
smooth-mouse:
boolean | any | any[]
optional
Whether enable mouse event or binding element(s).
- @default:
false
- @default:
-
smooth-touch:
boolean | any | any[]
optional
Whether enable touch event or binding element(s).
- @default:
false
- @default:
-
beforeAnimate:
NgxSmoothScrollBeforeAnimateEvent
Event triggers before scroll animation starts.
currentIndex
:number
, current child indextargetIndex
:number
, target child index
-
afterAnimate:
NgxSmoothScrollAfterAnimateEvent
Event triggers after scroll animation ends(or interrupted).
prevIndex
:number
, previous child indexcurrentIndex
:number
, current child index(if interrupted, auto detected current index or equal toprevIndex
)scrollCoords
:{ x: number; y: number; }
, current scroll coordination.
- containerEl: native container element.
readonly
- children: pure array of child elements.
readonly
- currentIndex:
number
, current index.readonly
-
scrollTo:
(destination, options) => Observable<{ x: number; y: number; }>
Scroll to given destination.
destination
:{ x?: number; y?: number; }
, destination coords,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
scrollToElement:
(el, options) => Observable<{ x: number; y: number; }>
Scroll to given element.
el
:ElementRef | HTMLElement
, target element,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
scrollToIndex:
(index, options) => Observable<{ x: number; y: number; }>
Scroll to given child index.
childSelector
must be set.index
:number
, target index,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
interrupt:
() => boolean
Interrupt current scroll animation(since
requestAnimationFrame
behaves asynchronously, useafterAnimate
to catch actual animation ends).- @return:
boolean
, whether interruption successful.
- @return:
new NgxSmoothScroll(containerEl, childSelector);
-
containerEl
:ElementRef | HTMLElement
required
Container element.
-
childSelector
:string
optional
Child element selector.
- containerEl:
HTMLElement
, native container element.readonly
- childSelector:
string
, selector of child element. - defaultOption:
NgxSmoothScrollOption
, default option object, see more.readonly
-
scrollTo:
(destination, options) => Observable<{ x: number; y: number; }>
Scroll to given destination.
destination
:{ x?: number; y?: number; }
, destination coords,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
scrollToElement:
(el, options) => Observable<{ x: number; y: number; }>
Scroll to given element.
el
:ElementRef | HTMLElement
, target element,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
scrollToIndex:
(index, options) => Observable<{ x: number; y: number; }>
Scroll to given child index.
childSelector
must be set.index
:number
, target index,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
interrupt:
() => boolean
Interrupt current scroll animation(since
requestAnimationFrame
behaves asynchronously, useObservable
to catch actual animation ends).- @return:
boolean
, whether interruption successful.
- @return:
A simple wrapper for
NgxSmoothScroll
.
-
createInstance:
(contaierEl, childSelector) => NgxSmoothScroll
Create
NgxSmoothScroll
instance.containerEl
:ElementRef | HTMLElement
, container element,required
childSelector
:string
, child element selector,optional
-
scrollTo:
(containerEl, destination, options) => Observable<{ x: number; y: number; }>
Create
NgxSmoothScroll
instance once and scroll to given destination.containerEl
:ElementRef | HTMLElement
, container element,required
destination
:{ x?: number; y?: number; }
, destination coords,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
scrollToElement:
(containerEl, childEl, options) => Observable<{ x: number; y: number; }>
Create
NgxSmoothScroll
instance once and scroll to given element.containerEl
:ElementRef | HTMLElement
, container element,required
childEl
:ElementRef | HTMLElement
, target element,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
scrollToIndex:
(containerEl, childSelector, index, options) => Observable<{ x: number; y: number; }>
Create
NgxSmoothScroll
instance once and scroll to given child index.childSelector
must be set.containerEl
:ElementRef | HTMLElement
, container element,required
childSelector
:string
, child element selector,required
index
:number
, target index,required
options
:NgxSmoothScrollOption
, scroll options, see more,optional
-
duration:
number
The scroll animation duration,
ms
.- @default:
600
- @default:
-
timingFunction:
string
The scroll animation timing function, support cubic-bezier.
'linear'
'ease'
'ease-in'
'ease-out'
'ease-in-out'
'cubic bezier'
: ex) '.13, 1.07, .51, 1.29', check more at cubic-bezier.com- @default:
'ease'
-
alignX:
'start' | 'center' | 'end'
X axis alignment.
- @default:
'start'
- @default:
-
alignY:
'start' | 'center' | 'end'
Y axis alignment.
- @default:
'start'
- @default:
-
stopOnArrival:
boolean
Whether stop scroll animation on arrival.
- @default:
false
- @default:
If you found any errors or have suggestion to this library, please open an issue.