Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kaliber5/ember-sticky-element

An ember component that mimics the functionality of `position: sticky`
https://github.com/kaliber5/ember-sticky-element

ember ember-addon

Last synced: 24 days ago
JSON representation

An ember component that mimics the functionality of `position: sticky`

Awesome Lists containing this project

README 

        
ember-sticky-element

==============================================================================



[![Build Status](https://travis-ci.org/kaliber5/ember-sticky-element.svg?branch=master)](https://travis-ci.org/kaliber5/ember-sticky-element)

[![Ember Observer Score](https://emberobserver.com/badges/ember-sticky-element.svg)](https://emberobserver.com/addons/ember-sticky-element)

[![npm version](https://badge.fury.io/js/ember-sticky-element.svg)](https://badge.fury.io/js/ember-sticky-element)

[![Greenkeeper badge](https://badges.greenkeeper.io/kaliber5/ember-sticky-element.svg)](https://greenkeeper.io/)



This Ember addon gives you the ability to make parts of your UI stick to the viewport when scrolling. 

Its semantics follow roughly the proposed [`position: sticky`](https://drafts.csswg.org/css-position/#sticky-pos) specs.



**See the [Demo App](https://kaliber5.github.io/ember-sticky-element/) for some examples!**



### Why should I use this



The mentioned CSS extension of `position: sticky` is still in a draft stage, and 

[not widely supported](http://caniuse.com/#feat=css-sticky) natively. While there are polyfills available, they lack

some features:

* you cannot change the styling of your sticky element based on its state of being sticky or not

* you cannot dynamically change the contents of the sticky element based on that state either



While there a probably a few jQuery plugins around for the same purpose, they might not always play well with Ember. 



So this addon adds a `sticky-element` component, that mimics the basic `position: sticky` behaviour.

Currently it only supports scrolling in the vertical direction, not horizontal stickiness yet. 



It leverages [ember-in-viewport](https://github.com/DockYard/ember-in-viewport) under the hood for its efficient 

viewport detection techniques.



Compatibility

------------------------------------------------------------------------------



* Ember.js v2.18 or above

* Ember CLI v2.13 or above

* Node.js v8 or above



Installation

------------------------------------------------------------------------------



```

ember install ember-sticky-element

```



Usage

------------------------------------------------------------------------------



Just wrap your content into the `sticky-element`:



```hbs

{{#sticky-element}}

  
Sticky Element


{{/sticky-element}}

```



This will make it flow with the other content when scrolling until it reaches the top of the viewport, at which point

it will get sticky. This effectively makes it `position: fixed`. *(Unfortunately for now this will require you to allow

inline styles if you use CSP!)*



### Customization options



#### Offsets



The behaviour of the component and its styling can be customized with the following options. Also see the [Demo App](https://kaliber5.github.io/ember-sticky-element/) for some examples.



##### Top offset



Add the `top` property to specify an offset in pixels from the top of the viewport:



```hbs

{{#sticky-element top=50}}

  
Sticky Element


{{/sticky-element}}

```



##### Bottom offset



By default the sticky element will not care about its parent enclosing element and just remain sticky to the top when 

scrolling the page all the way down. To make it also stick to the bottom of its parent (so it does not leave its parent's

boundaries), just add the `bottom` property, with a value of 0 or some other offset:



```hbs

{{#sticky-element top=50 bottom=0}}

  
Sticky Element


{{/sticky-element}}

```



Make sure that the parent element has some positioning applied, so at least `position: relative`, as sticking to the 

bottom is done by applying `position: absolute` to the sticky element!



##### Disabling



You can set the `enabled` property to false to disable the sticky behavior:



```hbs

{{#sticky-element enabled=someBooleanProperty}}

  
Sticky Element


{{/sticky-element}}

```



#### Styling



##### CSS



The sticky element has a `containerClassName` property you can use for styling (by default `.sticky-element`). Furthermore additionals classes can be set:

when being sticky:

* `containerStickyClassName` (by default `.sticky-element--sticky`): when sticked either to the top or the bottom.

* `containerStickyTopClassName` (by default `.sticky-element--sticky-top`): when sticked to the top.

* `containerStickyBottomClassName` (by default `.sticky-element--sticky-bottom`): when sticked to the bottom.



##### Content



The component yields a hash, that contains the following boolean properties based on its state:

* `isSticky`

* `isStickyTop`

* `isStickyBottom`



You can use these to change the content of the sticky element based on its state:



```hbs

{{#sticky-element as |state|}}

  
Sticky Element


  
{{#if state.isSticky}}Yeah, I am sticky!{{else}}I am just a normal element.{{/if}}


{{/sticky-element}}

```



Contributing

------------------------------------------------------------------------------



See the [Contributing](CONTRIBUTING.md) guide for details.



License

------------------------------------------------------------------------------



This project is licensed under the [MIT License](LICENSE.md).