@bw-ui/datepicker-positioning

Positioning plugin for BW DatePicker - Auto-flip, collision detection, and viewport constraints.

Live Demo • Documentation • Core Package

✨ Features

• 📍 Auto Positioning - Position relative to input
• 🔄 Auto Flip - Flip when near viewport edges
• 🚧 Collision Detection - Avoid overlapping viewport
• 📐 Multiple Placements - Top, bottom, left, right
• ↔️ Alignment Options - Start, center, end

📦 Installation

npm install @bw-ui/datepicker @bw-ui/datepicker-positioning

⚠️ Peer Dependency: Requires @bw-ui/datepicker core package

🚀 Quick Start

ES Modules

import { BWDatePicker } from '@bw-ui/datepicker';
import { PositioningPlugin } from '@bw-ui/datepicker-positioning';

const picker = new BWDatePicker('#date-input', {
  mode: 'popup',
}).use(PositioningPlugin);

CDN

<link
  rel="stylesheet"
  href="https://unpkg.com/@bw-ui/datepicker/dist/bw-datepicker.min.css"
/>

<script src="https://unpkg.com/@bw-ui/datepicker/dist/bw-datepicker.min.js"></script>
<script src="https://unpkg.com/@bw-ui/datepicker-positioning/dist/bw-positioning.min.js"></script>

<script>
  const picker = new BW.BWDatePicker('#date-input').use(
    BWPositioning.PositioningPlugin
  );
</script>

⚙️ Options

.use(BWPositioning.PositioningPlugin, {
  placement: 'bottom',
  alignment: 'start',
  autoFlip: true,
  offset: { x: 0, y: 8 },
  constrainToViewport: true,
})

Options Reference

| Option | Type | Default | Values | Description | | --------------------- | --------- | ---------------- | ------------------------------- | --------------------------------- | | placement | string | 'bottom' | 'top', 'bottom' | Position relative to input | | alignment | string | 'start' | 'left', 'center', 'right' | Alignment along placement axis | | autoFlip | boolean | true | true, false | Flip to opposite side if no space | | offset | object | { x: 0, y: 8 } | { x: number, y: number } | Offset from input (px) | | constrainToViewport | boolean | true | true, false | Keep picker inside viewport |

📍 Placement & Alignment

              alignment
           start  center  end
          ┌──────┬──────┬──────┐
    top   │  TL  │  TC  │  TR  │
          ├──────┼──────┼──────┤
placement │      │[INPUT]│      │
          ├──────┼──────┼──────┤
   bottom │  BL  │  BC  │  BR  │
          └──────┴──────┴──────┘

| Placement + Alignment | Position | | --------------------- | -------------------------- | | bottom + start | Below input, left aligned | | bottom + center | Below input, centered | | bottom + end | Below input, right aligned | | top + start | Above input, left aligned | | top + center | Above input, centered | | top + end | Above input, right aligned |

📖 Examples

Basic Usage

.use(BWPositioning.PositioningPlugin)
// Default: bottom, start aligned, auto-flip enabled

Position Above Input

.use(BWPositioning.PositioningPlugin, {
  placement: 'top'
})

Center Aligned

.use(BWPositioning.PositioningPlugin, {
  placement: 'bottom',
  alignment: 'center'
})

Right Aligned

.use(BWPositioning.PositioningPlugin, {
  placement: 'bottom',
  alignment: 'end'
})

Custom Offset

.use(BWPositioning.PositioningPlugin, {
  offset: { x: 0, y: 16 }  // 16px gap below input
})

Disable Auto Flip

.use(BWPositioning.PositioningPlugin, {
  autoFlip: false  // Always stay at specified placement
})

No Viewport Constraint

.use(BWPositioning.PositioningPlugin, {
  constrainToViewport: false  // Allow overflow outside viewport
})

🔄 Auto Flip Behavior

When autoFlip: true:

| Input Position | Default Placement | Flipped To | | ----------------------- | ----------------- | ---------- | | Near bottom of viewport | bottom | top | | Near top of viewport | top | bottom | | Near right of viewport | right | left | | Near left of viewport | left | right |

🔌 Combining with Other Plugins

import { BWDatePicker } from '@bw-ui/datepicker';
import { ThemingPlugin } from '@bw-ui/datepicker-theming';
import { PositioningPlugin } from '@bw-ui/datepicker-positioning';

const picker = new BWDatePicker('#date-input')
  .use(ThemingPlugin, { theme: 'dark' })
  .use(PositioningPlugin, { placement: 'top' });

📁 What's Included

dist/
├── bw-positioning.min.js      # IIFE build (for <script>)
└── bw-positioning.esm.min.js  # ESM build (for import)

🔗 Related Packages

| Package | Description | | ------------------------------------------------------------------------------------------------ | --------------- | | @bw-ui/datepicker | Core (required) | | @bw-ui/datepicker-theming | Dark mode | | @bw-ui/datepicker-accessibility | Keyboard nav | | @bw-ui/datepicker-mobile | Touch support | | @bw-ui/datepicker-input-handler | Input masking | | @bw-ui/datepicker-date-utils | Date utilities |

📄 License

MIT © BW UI

🐛 Issues

Found a bug? Report it here