• Stars
    star
    643
  • Rank 70,000 (Top 2 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 4 years ago
  • Updated 10 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🍦 Minimalistic, small, positioning engine. Build for high-performance, minimal footprint and maximum control over positioning behavior.

Logo

Ultra Tiny, Opinionated Positioning Engine

gzip size brotli size Build Status Download count No dependencies JSDelivr download count Current version Support me


Index is an ultra-tiny positioning engine. Hold up, isn't there PopperJS? Yeah - and PopperJS is great! But there are tons of features that, in most cases, you just might not need. This library is less than a third of PopperJS.

When should I use Nanopop and not PopperJS?

  1. Situations where you want full control over positioning, including handling events such as scrolling, and manual resizing.
  2. Performance-critical cases with lots of elements [...] nanopop will only makes changes if you say so.
  3. Poppers with minimal footprint such as drop-downs and tooltips which don't require that much configurability.
  4. You might have some special needs about how your popper behaves. Index exposes a function for the sole purpose of positioning something, use it in your own library!

This library was originally part of pickr - now ported to TS with tests and a few updates / bug-fixes.

Heads up! This is the readme for v2 - if you're looking for the first version head over here (v1 is not maintained anymore).

Getting Started

Install via npm:

$ npm install nanopop

Install via yarn:

$ yarn add nanopop

Include directly via jsdelivr:

<script src="https://cdn.jsdelivr.net/npm/nanopop/dist/nanopop.umd.js"></script>

Using JavaScript Modules:

import {
    reposition,   // Core, stateless function to reposition an element
    createPopper, // Stateful function which keeps track of your configuration
    defaults,     // A subset of nanopops options used as default values
    version       // Current version
} from 'https://cdn.jsdelivr.net/npm/nanopop/lib/nanopop.min.mjs'

🌟 Index is fully tree-shakable! E.g. if you only use reposition you'll probably end up with less than 500B code!

Usage

reposition(
    /* reference: */ document.querySelector('.btn'),
    /* popper: */ document.querySelector('.dropdown'),
    /* We're using the default options */
);

⚠ The popper-element must have set position to fixed.

β„Ή Because the default-container is document.documentElement you might have to increase the height of the html element to make room for your popper (e.g. html {height: 100vh;})

All options

import {reposition, createPopper} from 'nanopop';

// Using a object and reposition directly
const nanopop = reposition(reference, popper, {

    // The DOMRect of the container, it used the html-element as default.
    // You could also create your own boundary using a custon DOMRect (https://developer.mozilla.org/en-US/docs/Web/API/DOMRect)!
    container: document.documentElement.getBoundingClientRect(),

    // Optional arrow element that is positioned between the popper and the reference element.
    arrow: undefined,

    // Margin between the popper element and the reference
    margin: 8,

    // Minimum space between the popper and the container
    padding: 0,

    // Preferred position, any combination of [top|right|bottom|left]-[start|middle|end] is valid.
    // 'middle' is used as default-variant if you leave it out.
    position: 'bottom-middle',

    // In case the variant-part (start, middle or end) cannot be applied you can specify what (and if)
    // should be tried next.
    variantFlipOrder: {
        start: 'sme', // In case of -start try 'start' first, if that fails 'middle' and 'end' if both doesn't work.
        middle: 'mse',
        end: 'ems'
    },

    // The same as variantFlipOrder, but if all variants fail you might want to try other positions.
    positionFlipOrder: {
        top: 'tbrl', // Try 'top' first, 'bottom' second, 'right' third and 'left' as latest position.
        right: 'rltb',
        bottom: 'btrl',
        left: 'lrbt'
    }
});

/**
 * Using the createPopper function to create a stateful wrapper
 *
 * Correct ways of calling it are:
 * createPopper(reference: HTMLElement, popper: HTMLElement, options?: NanoPopOptions)
 * createPopper(options?: NanoPopOptions)
 * ⚠ If you omit options entierly you'll have to set both the reference and the popper later when calling .update!
 */
const popper = createPopper({...});
popper.update(); // You can pass an object to update which will get merged with the existing config.

Calling popper.update(...) or reposition(...) both returns a position-pair (For example te for Top-End) or null based on if it was possible to find a position for the popper without clipping it._

Tip: The returned position-pair is perfect for tool-tips to give them a little arrow!

Caveats

  1. The popper-element must have position set to fixed.
  2. If nanopop cannot find a position without clipping your popper it'll revert its top and left values - you can use css / js to handle this case.

More Repositories

1

pickr

🎨 Flat, simple, multi-themed, responsive and hackable Color-Picker library. No dependencies, no jQuery. Compatible with all CSS Frameworks e.g. Bootstrap, Materialize. Supports alpha channel, rgba, hsla, hsva and more!
JavaScript
4,290
star
2

selection

✨ Viselect - A high performance and lightweight library to add a visual way of selecting elements, just like on your Desktop. Zero dependencies, super small. Support for major frameworks!
TypeScript
2,494
star
3

candy

🍭 Cross-platform YouTube-downloader with playlist and channel support as well as build-in audio / video converter.
Vue
237
star
4

java-express

πŸ§ͺ HTTP Framework based on expressjs, no dependencies, simple usage. Can be used to quickly spin up an API or serve local files.
Java
196
star
5

presentr

Minimalistic javascript presentation-library. Zero dependencies. Can be used in combination with frameworks like Bootstrap, Materialize, Vue etc.
JavaScript
71
star
6

openvpn-pihole

πŸ•΅οΈ A truly delicious combination of two wonderful pieces of software to setup a pi.hole-backed VPN as quick as possible.
Shell
68
star
7

gpickr

Demo of pickr integrated into another widget. A gradient-picker.
JavaScript
60
star
8

ocular

πŸ’° Simplistic, beautiful and straight-forward budgeting app to track your budget across the years. Easy to use, to get started and to set up.
Vue
59
star
9

sassyfication

πŸ’…Library with sass mixins to speed up your css workflow.
SCSS
58
star
10

graceful-ws

πŸ”Œ Graceful WebSocket wrapper with connection re-establishment capabilities.
TypeScript
41
star
11

li18nt

🌎 Lint your i18n translation files. Detect conflicting properties, duplicates and make it more readable and easier to maintain by formatting it!
TypeScript
38
star
12

nason

πŸ“¦ Ultra tiny serializer / encoder with plugin-support. Useful to build binary files containing images, strings, numbers and more!
TypeScript
35
star
13

vite-plugin-optimize-css-modules

πŸ—œ Mangle / minimize css module classnames in production like facebook and Google do!
TypeScript
28
star
14

cinematic

πŸ“½οΈ Ultra tiny library to add cinematics to your HTML5 videos!
TypeScript
22
star
15

conway

πŸ•Ή Supercharged version of conways game-of-life brought to life by wasm and workers.
TypeScript
12
star
16

spectrum

πŸŽ™οΈ Fast, installable, in-browser audio spectrum visualizer. Support for both realtime and audio files!
TypeScript
11
star
17

bavary

🧬 Regular expressions on steroids. Parse anything and everything with a syntax - crafted to parse syntax. A super-set of regular-expressions.
TypeScript
10
star
18

eslint-plugin-align-import

βš™ ESLint plugin to align all your import statements.
JavaScript
8
star
19

ocular-docker

Ready-to-use docker compose setup for ocular ✨
Shell
8
star
20

widgetify

Simple widget library which helps to quickly create a new, responsive, interactive widget or ui tool.
JavaScript
7
star
21

intl-demo

Interactive demo of the ECMAScript Internationalization API
JavaScript
5
star
22

yuppee

βš™οΈ Type-safe migration library to migrate data from one schema to another.
TypeScript
4
star
23

reinisch.io

πŸ”² My Personal Homepage :)
TypeScript
3
star
24

reactivity-playground

πŸ’« Simple recreation of reactivity as its mainly used in Vue3
TypeScript
3
star
25

cssvjs

Fast, spec-conform css-value parser written entirely in vanilla JavaScript. Can be used in any environment.
JavaScript
3
star
26

cleanup-files

🧼 Small utilities to cleanup directories such as download which are all the time full of random stuff.
Rust
1
star
27

genesis

🧞 A simple, generic, fast and lightweight json api for frontend apps. Store your frontend-data as-is without messing around with a database!
Go
1
star
28

bavary-webpack-loader

Webpack loader for bavary declarations
JavaScript
1
star
29

eslint-config-simon

βš™ Eslint config files for my personal projects.
JavaScript
1
star
30

previous-index-of

Find the previous index of a char-sequence at a given offset in a string
JavaScript
1
star
31

bavary-cli

Bavary CLI
TypeScript
1
star