derenko / np-select

Nova Poshta © city and warehouse selects.

Description

This library is created to make life easier for fellows who needs to implement, NovaPoshta © address and warehouse selects. It contains two selects, which requires almost zero configuration.

Advantages:

⭐ TypeScript Types

⭐ Zero configuration

⭐ Robust API

Table of Contents

• Installation

• NpCitySelect

• NpWarehouseSelect

• Properties

• Hooks

• Methods

• Styling

  • Classnames
  • Active states
  • Variables

• Example Usage

• Common Cases

  • Warehouse select disabled untill city is not selected
  • Validate select
  • Validate multiple selects with validateMultiple
  • Get select value

---

Installation

Script tag:

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/build/np-select.umd.js"></script>

• Also you can go to /build folder and download np-select.umd.js, np-select.d.ts if you want to have .ts types

Now select is availiable under NpSelect global variable:

document.addEventListener('DOMContentLoaded', () => {
  NpSelect.NpCitySelect({...});
  NpSelect.NpWarehoseSelect({...});
});

Package managers:

npm install --save np-select

yarn add np-select

import { NpCitySelect, NpWarehouseSelect, utils } from 'np-select';

NpCitySelect({...});
NpWarehouseSelect({...});

NpCitySelect:

This select is searchable and it fetches Nova Poshta cities on user input.

  NpCitySelect({
    apiKey: API_KEY,
    input: {
      name: 'city',
      placeholder: 'Select City',
    },
    button: {
      text: 'Select City',
    },
    root: document.querySelector('#city'),
  });

NpWarehouseSelect:

Name	Type	Description
city?	string	if passed select will fetch warehouses for this city

This select is filterable and it filters passed options on user input.

• If passed city NpCitySelect will fetch all warehouses for this city when mounted

  NpCitySelect({
    apiKey: API_KEY,
    input: {
      name: 'city',
      placeholder: 'Select City',
    },
    button: {
      text: 'Select City',
    },
    root: document.querySelector('#city'),
    city: 'Київ'
  });

Shared Properties:

List of configuration properties when you creating selects

Name	Type	Description
root	HTMLElement	root html element
apiKey	string	Your NovaPoshta API_KEY
input?	{ name: string, placeholder: string }	input props
button?	{ text: string }	button props
placeholder?	{ text: string }	placeholder props
options?	{ label: string; value: string }[]	initial list of options
getOption?	(item: ApiResponse) => {label: string, value: string}[]	method to extract property and value from ApiResponse

Hooks:

Name	Type	Description
onMounted	(select) => void	called after select is mounted
onSelect	(item, select) => void	called when item is selected.
onOpen	(select) => void	called when select opened, if onOpen returns false, select will not be opened
onInput	(value: string, select) => void	called when input value changes

Methods

Name	Type	Description
validate	() => boolean	validates select
getFiltered	() => {label: string, value: string}[]	returns filtered options
setFiltered	(options: {label: string, value: string}[]) => void	set filtered options
getOptions	() => {label: string, value: string}[]	returns all options
setOptions	(options: {label: string, value: string}[]) => void	set all options
setOpen	(open: boolean) => void	open or close select
getOpen	() => boolean	return is select open
setDisabled	(disabled: boolean) => void	disable or enable select
getDisabled	() => boolean	returns is select disabled
getValue	() => string	get input value
setValue	(value: string) => string	set input value
setLoading	(loading: boolean) => void	set select loading
getLoading	() => boolean	get is select loading

Styling

ClassNames:

Class	Type
.np-select	Select classs
.np-select__button	Select button
.np-select__input	Select input
.np-select__box	Options box class
.np-select__option	Option class

Active states:

Class	Type
.np-select[aria-invalid='true']	Invalid/error class
.np-select[aria-busy='true']	Loading class
.np-select[aria-disabled='true']	Disabled class
.np-select.open	Select open class
.np-select__option.selected	Option selected class

CSS variables:

Name	Description	Default Value
--np-select-error	Error color	tomato
--np-select-white	White color	#fff
--np-select-text	Text color	#221f1f
--np-select-active	Active color	#e5f5ec
--np-select-disabled	Disabled color.	#d2d2d2
--np-select-box-shadow	Box shadow color	#221f1f40

Example usage:

import NpSelect from 'np-select';

NpSelect.NpCitySelect({
  root: document.querySelector('#city'),
  apiKey: API_KEY,
  input: {
    name: 'city',
  },
  button: {
    text: 'Select City',
  },
});

NpSelect.NpWarehouseSelect({
  root: document.querySelector('#warehouse'),
  apiKey: API_KEY,
  input: {
    name: 'warehouse',
  },
  button: {
    text: 'Select Warehouse',
  },
});

Common cases:

Warehouse select disabled untill city is not selected:

Most common case:

const warehouseSelect = NpWarehouseSelect({
  apiKey: API_KEY,
  input: {
    name: 'warehouse',
    placeholder: 'Select Warehouse',
  },
  button: {
    text: 'Select Warehouse',
  },
  root: document.querySelector('#warehouse'),
  onMounted: select => select.setDisabled(true),
});

NpCitySelect({
    apiKey: API_KEY,
    input: {
    name: 'city',
     placeholder: 'Select City',
    },
    button: {
     text: 'Select City',
    },
    root: document.querySelector('#city'),
      onSelect: async (item, select) => {
      const warehouses = await select.api.getNpWarehouses(item.value);
    
      warehouseSelect.setOptions(warehouses);
      warehouseSelect.setDisabled(false);
      warehouseSelect.setOpen(true);
    },
  });
});

Validate select on form submit:

Library provides error styles for select, which you can modify with css.

form.addEventListener('submit', e => {
  e.preventDefault();
  const isValid = warehouseSelect.validate();

  if (!isValid) {
    return;
  }
});

Validate multiple selects on form submit:

For this case you can use utility method validateMultiple()

form.addEventListener('submit', e => {
  e.preventDefault();
  const isValid = NpSelect.validateMultiple([warehouseSelect, citySelect]);

  if (!isValid) {
    return;
  }
});

Get select value:

Getting value as easy as getting it from <input /> element, or using getValue method

form.addEventListener('submit', e => {
  e.preventDefault();
  const isValid = NpSelect.validate(citySelect);

  if (!isValid) {
    return;
  }
  
  // Using getValue
  const city = citySelect.getValue();

  // Using form data
  const form = new FormData(e.target);
  const city = form.get('city');

  // Using querySelector
  const city = document.querySelector('[name="city"]').value;
});

np-select's Issues

Type 'HTMLElement | null' is not assignable to type 'HTMLElement'. Type 'null' is not assignable to type 'HTMLElement'.ts(2322)

Hi, tried this library with the nuxt3 framework, and got an error:

Type 'HTMLElement | null' is not assignable to type 'HTMLElement'.
Type 'null' is not assignable to type 'HTMLElement'.ts(2322)
np-select.d.ts(85, 2): The expected type comes from property 'root' which is declared here on type 'NpCitySelectConfig'

<template>
    <div>
        Nova Poshta Field

        <input type="text" id="city">
    </div>
</template>

<script setup lang="ts">
import { NpCitySelect, NpWarehouseSelect, utils } from 'np-select';

NpCitySelect({
    apiKey: 'b87d9e34dd42ed852b7b1f0bb....1212',
    input: {
      name: 'city',
      placeholder: 'Select City',
    },
    button: {
      text: 'Select City',
    },
    root: document.querySelector('#city'),
  });

</script>

Any ideas on how to fix this?