@lemon3/birthdaypicker

an i18n javascript birthday picker

Table of Contents

• About The Project
• Usage
• Api
• Getting Started
• License
• Contact

About The Project

I needed a birthday input field that is easy to use and without JS dependencies. "Simple" in this context means: with as few clicks as possible to the result!

Features

• Coded in vanilla JS.
• internationalisation (i18n)
• BirthdayPicker is dependency-free ;)

BirthdayPicker Demo >>

(back to top)

Usage

First Steps

classic js approach

if you use the classic js approach by loading scripts in html code, just dowload and integrate the birthdaypicker.min.js script in your code:

<div id="my-div"></div>
<script src="path/to/birthdaypicker.min.js"></script>
<script>
  // BirthdayPicker is now defined
  const bp = new BirthdayPicker('#my-div');
</script>

module js approach

use npm / yarn to install the package

npm install @lemon3/birthdaypicker
# or
yarn add @lemon3/birthdaypicker

and then us it with

<div id="my-div"></div>
<script type="module" defer>
  import BirthdayPicker from './node_modules/@lemon3/birthdaypicker/index.js';
  // BirthdayPicker is now defined
  const bp = new BirthdayPicker('#my-div');
</script>

Examples via data API

html:

<!-- with default values -->
<div data-birthdaypicker></div>

<!-- with current date -->
<div
  data-birthdaypicker
  data-birthdaypicker-default-date="now"
></div>

<!-- with arrangement set to: day | month | year -->
<div
  data-birthdaypicker
  data-birthdaypicker-arrange="dmy"
></div>

<!-- with language set to 'fr' and current date -->
<div
  data-birthdaypicker
  data-birthdaypicker-locale="fr"
  data-birthdaypicker-default-date="now"
></div>

<!-- using the inline-json to set multiple values -->
<div
  data-birthdaypicker="{'locale':'de','arrange':'dmy'}"
></div>

<!-- using the settings string -->
<div
  data-birthdaypicker="locale:fr,defaultDate:now,arrange:dmy"
></div>

Example via data API (select boxes in DOM)

Select-boxes boxes must be inside the main container (where the data-birthdaypicker attribute is defined)! If the data attributes are set to the select-boxes, the plugin knows which box should be used for what. Correct syntax for the data attributes (select element):

• year: data-birthdaypicker-year
• month: data-birthdaypicker-month
• day: data-birthdaypicker-day

This scenario (select-boxes in DOM) works best with tailwindcss, as the select-boxes can be styled with classes here.

:memo: INFO
If select-boxes already exist in the DOM you cannot use the arrange option, eg.: { arrange: 'dmy' }, as this plugin doesn't rearrange existing Elements

html:

<div data-birthdaypicker>
  <select data-birthdaypicker-year></select>
  <select data-birthdaypicker-month></select>
  <select data-birthdaypicker-day></select>
</div>

... or use with specified selctors (these selctors take precedence over the data attribute values like data-birthdaypicker-year)

html:

<div data-birthdaypicker="{
  'yearEl':'#myYear',
  'monthEl':'#myMonth',
  'dayEl':'.myDay'
}">
  <select id="myYear"></select>
  <select id="myMonth"></select>
  <select class="myDay"></select>
</div>

Example via js

html

<div id="bp1"></div>
<div id="bp2"></div>

<script src="path/to/birthdaypicker.min.js"></script>
<script>
  // initialize with default values
  const bp1 = new BirthdayPicker('#bp1');

  // initialize with current date (new Date(), or 'now')
  const el = document.getElementById('bp2');
  // see 'option API' section for all available options
  const options = { defaultDate: new Date() };
  const bp2 = new BirthdayPicker(el, options);
</script>

(back to top)

API

note: the API may change ...

initialize

// element: a dom reference to one element, or a querySelector string
const element = '#my-div';
// an options-object, see below
const options = {};
const myBirthdayPicker = new BirthdayPicker(element, options);

option API

options = {
  // sets the minimal age for a person, animal,...
  // if set > 0 it changes the maximal selectable year by it's value
  // e.g.: maxYear: 2022, minAge: 10 -> max selectable year: 2012!
  // default: 0
  // example: 10
  minAge: 0,

  // sets the maximal age for a person, animal,...
  // min selectable year is 1922 if maxYear is 2022 (2022 - 100)
  // default: 100,
  maxAge: 100,

  // sets the minimal year (overrides maxAge)
  // default: null
  // example: 1980
  minYear: null,

  // sets the maximal year
  // default: '(new Date()).getFullYear()'
  // example: 2040 | 'now'
  maxYear: 'now',

  // sets the month format for the select box
  // available: 'short', 'long', 'numeric'
  // default: 'short'
  monthFormat: 'short',

  // shows a placeholder for each select box
  // available: true | false
  // default: true
  placeholder: true,

  // sets the selected start date
  // available: 'now' | new Date() | '2020-10-12' (YYYY-MM-DD)
  // default: null
  // example: '2012-12-04'
  defaultDate: null,

  // if the initialize function should be called on creating an instance:
  // const myBp = new BirthdayPicker(el, {})
  // if set to false, you have to call myBp.init() afterwards.
  // available: true | false
  // default: true
  autoinit: true,

  // if the month and day values in the select-box should have a leading
  // zero or not. If set to true, you will get: 01, 02, 03, ... 10, 11, ...
  // if set to false, you will get: 1, 2, 3, ... 10, 11, ...
  // available: true | false
  // default: true
  leadingZero: true,

  // sets the language to be used
  // available: 'en', 'de', 'fr', ... all country codes with 2chars (ISO 3166-1 alpha-2)
  // default: 'en'
  locale: 'en',

  // if it should be possible to select a 'future' date
  // false means: unable to select a date in the future
  // available: true | false
  // default: false
  selectFuture: false,

  // to arrange the select-boxes
  // y: year, m: month, d: day
  // so ymd means:  year | month | day
  // ordering is only available, if select boxes are not present in the DOM
  // available: 'ymd', 'ydm', 'myd', 'mdy', 'dmy', 'dym'
  // default: 'ymd'
  arrange: 'ymd',

  // specify a custom select-box for the year
  // must be inside the main element
  // all valid query-strings allowed
  // default: null
  // example: '#my-year-select'
  yearEl: null,

  // specify a custom select-box for the month
  // must be inside the main element
  // all valid query-strings allowed
  // default: null
  // example: '#my-month-select'
  monthEl: null,

  // specify a custom select-box for the day
  // must be inside the main element
  // all valid query-strings allowed
  // default: null
  // example: '#my-day-select'
  dayEl: null,
};

methods

const element = '#my-div';
const options = {
  autoinit: false
};
const myBirthdayPicker = new BirthdayPicker(element, options);

// init: initializes the picker
myBirthdayPicker.init();

// getDate returns the current selected date with the language default date-formating!
// you can change the format, by calling the method with a specific data-format value.
// e.g.: 'yyyy-m-d'
// if date is 2. Sep. 1994
// return values are:
// 'yy'   -> 94
// 'yyyy' -> 1994
// 'mm'   -> 09
// 'm'    -> 9
// 'dd'   -> 02
// 'd'    -> 2
myBirthdayPicker.getDate('yyyy-m-d');

// just a small helper function, returns true or false
myBirthdayPicker.isLeapYear(2020); // true

// listen to different events eg.
// available events: init | datechange
const myEventListener = () => {};
myBirthdayPicker.addEventListener('datechange', myEventListener, false);

// remove the eventlistener
myBirthdayPicker.removeEventListener('datechange', myEventListener);

// set the date to a given value
// e.g.: '2020-10-22' // yyyy-mm-dd: this is the 22. oct. 2020
// or to the current date with new Date()
myBirthdayPicker.setDate(new Date());

// sets the language for the current instance
// e.g.: 'en', 'de', 'fr', ...
myBirthdayPicker.setLanguage('en');

// sets the month format for the current instance
// available: 'short', 'long', 'numeric'
myBirthdayPicker.setMonthFormat('short');

// setter, if the
myBirthdayPicker.useLeadingZero(true); // true | false

// kills the current instance and removes all event-listeners
myBirthdayPicker.kill();

Demo

A small demo of this tool can be view here: BirthdayPicker Demo

(back to top)

Getting Started

Prerequisites

you need to have node with npm and/or yarn. skip to installation if you already have this ;)

• Install node via brew (or download here) this will install npm too.

  brew install node
  

• Install yarn: via npm:

  npm install --global yarn
  

  test version, to see if it works:

  yarn --version
  

Installation

how to install

• Clone the repo

  git clone https://github.com/lemon3/birthdaypicker.git
  

• cd into the cloned repo

  cd birthdaypicker
  

• Install NPM packages

  yarn install
  # or
  npm install
  

• start (opens a dev server at port 8080, with root set to ./examples directory)

  yarn run start
  # or
  npm run start
  

To see all available scripts, open the package.json file or run either

yarn run
# or
npm run

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Wolfgang Jungmayer - lemon3.at

Project Link: https://github.com/lemon3/birthdaypicker

(back to top)

coded with ❤ in vienna
by wolfgang jungmayer