react-coordinate-input

react-coordinate-input

A masked input React component for entering latitude & longitude coordinates as Degree Minute Second (DMS) values, with built-in conversion to Decimal Degrees.

Features

• Masked input with imaskjs
• Coordinate validation
• Conversion to decimal degrees
• Accepts decimal degree passed in as value prop
• Second precision up to 6 decimal places
• Decimal degree precision up to 8 decimal places

Demo

Install

npm install --save react-coordinate-input

Usage

import React from 'react'
import CoordinateInput from 'react-coordinate-input'

const Example = () => {
  return (
    <CoordinateInput
      onChange={(value, { unmaskedValue, dd, dms }) => {
        console.log(value, unmaskedValue, dd, dms)
      }}
    />
  )
}

Props

Component props and their default values.

{
  // See below for more info on the onChange callback
  onChange: undefined,
  // Input placeholder; this will only be visible if `placeholderChar` is set to `null`
  placeholder: '04° 08′ 15″ N 162° 03′ 42″ E',
  // Number of decimal places to round decimal degrees to (0-8)
  ddPrecision: 6,
  // Number of decimal places for Seconds value on input (0-6)
  dmsPrecision: 0,
  // Callback function which receives the input ref
  inputRef: undefined,
  // DMS characters used in the input mask
  degreeChar: '°',
  minuteChar: '′',
  secondChar: '″',
  spacerChar: ' ',
  // The placeholder character represents the fillable spot in the input mask
  // Setting this to null will not display the mask guides
  placeholderChar: '_',
  // Input value -- see below for more info
  value: undefined,
}

onChange

The onChange callback will only trigger once a valid coordinate has been entered or the input has been cleared.

The callback receives two arguments, the first being the masked input value, e.g. 90° 00′ 00″ N 180° 00′ 00″ W, and the second is an object with three properties:

{
  // The normalized DMS value
  unmaskedValue: '900000N1800000W',
  // The DMS value converted to Decimal Degrees
  dd: [90, -180],
  // DMS values split into an array of arrays,
  // e.g. [[D, M, S, 'N|S'], [D, M, S, 'E|W']]
  dms: [
    [90, 0, 0, 'N'], [180, 0, 0, 'W']
  ]
}

Input value

When providing a value to the input the following formats are supported:

• DMS value which conforms to the input mask, e.g. 04° 08′ 15″ N 162° 03′ 42″ E

Note: The DMS symbols and spaces are not required; a minimal input would also work, e.g. 040815N1620342E

The only requirement is that each value has the required number of characters, i.e. 04 not 4 for degrees, minutes, seconds, etc., except for longitude degrees which requires three characters.

• Decimal degree string can also be used, e.g. 4.1375, 162.061667

The component will detect the DD value and convert it to a DMS value automatically.

Exports

In addition to the default CoordinateInput export, the following helper utilities are also exported for convenience:

dmsToDecimal

/**
 * dmsToDecimal
 *
 * Converts Degrees Minutes Seconds to Decimal Degrees
 *
 * Formula:
 * DD = D + M / 60 + S / 3600
 *
 * @param {number} degrees
 * @param {number} minutes
 * @param {number} seconds
 * @param {string} direction Compass direction, e.g. N|S|E|W
 * @param {number} [precision]  Decimal places (default: 6)
 * @returns {number} Decimal degrees, e.g. 42.451
 */

decimalToDMS

/**
 * decimalToDMS
 *
 * Converts Decimal Degress to Degrees Minutes Seconds
 *
 * @param {number} dd Decimal degree value
 * @param {boolean} isLon Is longitude?
 * @param {number} [precision] Decimal places for seconds (default: 0)
 * @returns {(string|number)[]} DMS values, e.g. [D, M, S, 'N|S|E|W']
 */

License

MIT © Justin M. Williams