๐Ÿญ search-buddy ultra lightweight javascript plugin that can help you create instant search and/or facilitate navigation between pages.

Overview

๐Ÿญ search-buddy

search-buddy js plugin

release workflow result search-buddy total downloads search-buddy version search-buddy license

search-buddy is an openโ€‘source ultra lightweight javascript plugin (* <1kb). It can help you create instant search and/or facilitate navigation between pages. It was written in pure JS without any dependencies, those make it ultra lightweight. * ~0.2kb after gzip.

It is especially useful in projects that are stuck in complex navigation structures (e.g. admin panel). It will surely make your users' everyday things more enjoyable.

Features

  • key shortcut (e.g. doubleShiftLeft, Ctrl+/, doubleEscape and so on)
  • arrow navigation
  • cache mechanism (sessionStorage)
  • built-in search algorithm, you just pass the items to be searched
  • dynamic mode - you can pass an array of items or an async function where you can call your API to fetch items.
  • responsive design
  • and more, please check Live demo!

search-buddy js plugin

Installation

npm i search-buddy

Usage

import { SearchBuddy } from 'search-buddy';

let searchBuddy = SearchBuddy({
    items: [
        { title: "Settings", path: "/settings", icon: "๐Ÿ› ๏ธ" },
        { title: "Users", path: "/users", icon: "๐Ÿ‘ฅ๏ธ" }
    ],
    keyShortcut: "doubleShiftLeft",
});

// optionally: you can also bind click events to searchBuddy.show
document.querySelector("#search-btn").addEventListener("click", searchBuddy.show);

You also need to load styles, you can import styles in scss

@import 'search-buddy';

or via javascript (you may need a css loader)

import 'search-buddy/dist/esm/index.css'

Installation via CDN (jsDelivr)

This script contains all javascript and css styles, there is no need to load any additional file.

<script src="https://cdn.jsdelivr.net/npm/search-buddy@latest/dist/standalone.min.js"></script>
<script>
  let searchBuddy = SearchBuddy({
    items: [
      { title: "Settings", path: "/settings", icon: "๐Ÿ› ๏ธ" },
      { title: "Users", path: "/users", icon: "๐Ÿ‘ฅ๏ธ" }
    ],
    keyShortcut: "doubleShiftLeft",
  });
</script>

Configuration

Options with default values

SearchBuddy({
  /**
   * The URL the user will be redirected to if there are no results
   * and the user clicks Enter. The search value will be appended to this URL.
   * 
   * @example: "/search?query="
   */
  fallbackSearchUrl: null,

  /**
   * It can be an array or an async function. 
   * 
   * @example [ {title: "Page", path: "/page", } ]
   * or
   * @example async () => {
            return new Promise((resolve, reject) => {
                // call your API
            })
        }
   */
  items: [],
  /**
   * Key shortcut used to activate search-buddy.
   * There is a naming convention. If you want to listen for a double click,
   * then use "double[keyCode]" where [keyCode] is the code of the key.
   * In case you want to use two key press event,
   * use the key code separated by a plus sign.
   *
   * Key codes: https://w3c.github.io/uievents/#dom-keyboardevent-code
   *
   * @example "doubleShiftLeft"
   * @example "doubleEscape"
   * @example "Ctrl+/"
   */
  keyShortcut: null,
  /**
   * The maximum number of items rendered in search box.
   */
  maxResults: 25,
  /**
   * The placeholder for search input.
   */
  placeholder: "Start typing...",
  /**
   * Flag to enable saving results to sessionStorage.
   * It is especially useful when loading items via API.
   */
  stateSave: false,
  /**
   * The time threshold (ms) for double clicks.
   * It is used only if keyShortcut is passed.
   */
  threshold: 1000,
  /**
   * Show/hide emojis.
   */
  withIcons: true,
})

Instance

Whenever you run SearchBuddy(options) the new instance will be created. The instance contains some public attributes and methods. You should avoid creating multiple instances, the idea is to have one instance per entire app.

Usually there is no need to manually interact with the instance, but if you want to use it anyway then here you have a little docs:

// Let's create an instance
const searchBuddy = SearchBuddy(options);

/**
 * Reference to DOM element
 */
searchBuddy.container

/**
 * Manually opens a container
 */
searchBuddy.show()

/**
 * Manually hides a container
 */
searchBuddy.hide()

/**
 * Manually destroys DOM elements and removes all event listeners 
 */
searchBuddy.destroy()

Digging Deeper

fetch items with async

As you know, it may happen that you have much more URLs, then the recommended solution is to pass an async function for items parameter and enable the session storage cache.

Instead of passing array you can simply pass an async function, this function will be resolved by search-buddy. This function MUST return just an array of items.

SearchBuddy({
    items: async () => { /* ... */ },
    stateSave: true, // <-- enable cache with sessionStorage
    keyShortcut: "doubleShiftLeft",
});

async example

SearchBuddy({
    keyShortcut: "doubleShiftLeft",
    stateSave: true,
    items: async () => {
        const getData = () => {
            return fetch('/api/search-buddy-items.json')
                .then(response => response.json())
                .then(data => data);
        };
        return new Promise((resolve, reject) => {
            resolve(getData());
        });
    },
});

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

You might also like...

Your emergency buddy and agent.

Your emergency buddy and agent.

S.H.I.E.L.D: To make you Beware of your surrounding The main aim of the S.H.I.E.L.D is to safeguard the individual and also make them aware about the

Oct 2, 2022

e-ONG, an authorial project, whose objective is to help ONGs to find people who need help or would like to help them

This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: npm start Runs the app in the developmen

Nov 11, 2022

๐Ÿถ Puppy Buddy ๊ฐ•์•„์ง€์˜ ์นœ๊ตฌ ๋งŒ๋“ค๊ธฐ, ๊ฐ•์•„์ง€์˜ ํ–‰๋ณต์„ ์œ„ํ•˜์—ฌ! ๐Ÿบ

๐Ÿถ Puppy Buddy ๊ฐ•์•„์ง€์˜ ์นœ๊ตฌ ๋งŒ๋“ค๊ธฐ, ๊ฐ•์•„์ง€์˜ ํ–‰๋ณต์„ ์œ„ํ•˜์—ฌ! ๐Ÿบ

๐Ÿ’ซ seb39_pre_019์˜ main-project ๐Ÿถ PuppyBuddy(ํผํ”ผ๋ฒ„๋””) ๐Ÿถ ์šฐ๋ฆฌ ์‚ฌ๋ž‘์Šค๋Ÿฌ์šด ๋ฉ๋ฉ์ด์˜ ์‚ฐ์ฑ… ์นœ๊ตฌ๋ฅผ ๋งŒ๋“ค์–ด ์ฃผ๊ณ  ์‹ถ๋‹ค๋ฉด PuppyBuddy(ํผํ”ผ๋ฒ„๋””)์™€ ํ•จ๊ป˜ํ•ด์š”! ๊ฐœ๋ฐœ๊ธฐ๊ฐ„: 2022.09.07 ~ 2022.10.12 ๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€?

Nov 24, 2022

On this page, you can save and load all the awesome books you have and save the name and the author into the local storage. this project uses Javascript to interact with the pages

Awesome Books: refactor to use JavaScript classes In this project, We add the links to the applications into the final project Getting Started if you

Nov 29, 2022

๐Ÿ‰ Water is a micro-ORM + QueryBuilder designed to facilitate queries and operations on PostgreSQL databases designed to work in Melon

๐Ÿ‰ Water Water is a micro-ORM + QueryBuilder designed to facilitate queries and operations on PostgreSQL databases designed to work in MelonRuntime In

Aug 6, 2022

App that leverages GPT-3 to facilitate new language listening and speaking practice.

App that leverages GPT-3 to facilitate new language listening and speaking practice.

Talk w/GPT-3 app: Getting started The Talk w/GPT-3 application was developed by James L. Weaver (the author of this document) to get more new language

Jan 1, 2023

Visualize, modify, and build your database with dbSpy! An open-source data modeling tool to facilitate relational database development.

Visualize, modify, and build your database with dbSpy! An open-source data modeling tool to facilitate relational database development.

Visualize, modify, and build your database with dbSpy! dbSpy is an open-source data modeling tool to facilitate relational database development. Key F

Dec 22, 2022

Types generator will help user to create TS types from JSON. Just paste your single object JSON the Types generator will auto-generate the interfaces for you. You can give a name for the root object

Types generator will help user to create TS types from JSON. Just paste your single object JSON the Types generator will auto-generate the interfaces for you. You can give a name for the root object

Types generator Types generator is a utility tool that will help User to create TS Interfaces from JSON. All you have to do is paste your single objec

Dec 6, 2022
Owner
Michael
Halting problem(s) ๐Ÿ‘จโ€๐Ÿ’ป
Michael
jQuery plugin to show a tabs bar for navigation. The tabs can be defined once, and shared across multiple HTML pages.

jquery.simpletabs v1.2.3 The jquery.simpletabs plugin shows a tabs bar for navigation. The tabs can be defined once, and shared across multiple HTML p

Peter Thoeny 1 Feb 23, 2022
Navigation-Menu-Javascript - A simple Navbar navigation using vanilla javascript, to change links to the active link when clicked.

Navigation-Menu-Javascript A simple Navbar navigation using vanilla javascript, to change links to the active link when clicked. Desktop view Mobile v

Ellis 2 Feb 16, 2021
A lightweight (<1Kb) JavaScript package to facilitate a11y-compliant tabbed interfaces

A11y Tabs A lightweight (<1Kb) JavaScript package to facilitate a11y-compliant tabbed interfaces. Documentation โ†— Demo on Codepen โ†— Features: Support

null 5 Nov 20, 2022
DoMe is a ToDo App. you can add, delete and reorder elements of the todo list using drag and drop. You can also toggle between dark&light mode

DO ME Todo App Live Preview : DO ME Built With : - ReactJS - TailwindCSS Make sure you have: - Git - Nodejs version 14 or higher (we recommend using

Medjahdi Islem 5 Nov 18, 2022
An ultra-lightweight self-hosted CI solution with a dashboard and containerized runners

An extremely simple containerized CI server. Ecosystem The Candor ecosystem is straightforward, and entirely containerized. Docker runs on the host ma

Paul Huebner 8 Nov 20, 2022
Simple shopping cart prototype which shows how React components and Redux can be used to build a friendly user experience with instant visual updates and scalable code in e-commerce applications.

This simple shopping cart prototype shows how React components and Redux can be used to build a friendly user experience with instant visual updates a

Ivan Kuznietsov 3 Feb 8, 2022
The website which can help you to organize your daily or weekly activities and review them when you need them. you can add, remove and delete an activity

To Do list To do project is webpack project that list activities someone can do at a specific time In this TO-DO list, you can add or remove you activ

Joffrey NKESHIMANA 5 Jul 21, 2022
Your emergency buddy and agent.

S.H.I.E.L.D: To make you Beware of your surrounding The main aim of the S.H.I.E.L.D is to safeguard the individual and also make them aware about the

Prathik Shetty 6 Oct 2, 2022