np-select v1.0.3

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/np-select@1.0.3/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:

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

Hooks:

Methods

Styling

ClassNames:

Active states:

CSS variables:

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;
});