Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/teamwork/vue-dropdown-directive
A vue.js directive for handling dropdowns
https://github.com/teamwork/vue-dropdown-directive
directive dropdown teamwork vue vuejs
Last synced: 3 days ago
JSON representation
A vue.js directive for handling dropdowns
- Host: GitHub
- URL: https://github.com/teamwork/vue-dropdown-directive
- Owner: Teamwork
- License: mit
- Created: 2018-08-07T08:18:56.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-11-05T14:25:20.000Z (9 days ago)
- Last Synced: 2024-11-05T15:32:09.325Z (9 days ago)
- Topics: directive, dropdown, teamwork, vue, vuejs
- Language: JavaScript
- Homepage: https://developer.teamwork.com/
- Size: 1.73 MB
- Stars: 9
- Watchers: 35
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Vue Dropdown Directive
## Table of contents
1. [Installation](#installation)
2. [Basic usage](#basic-usage)
3. [Modifiers](#modifiers)
4. [Parameters](#parameters)
5. [Behaviour](#behaviour)
6. [Methods](#methods)
## Installation
```bash
$ npm install @teamwork/vue-dropdown-directive
```
## Basic usage
```html
Show list
```
```js
import DropdownDirective from '@teamwork/vue-dropdown-directive';
const directives = {
DropdownDirective,
};
const ExamplePage = {
props,
directives,
computed,
methods,
...,
};
export default ExamplePage;
```
## Modifiers
``.bottom`` and ``.center`` are applied by default. If only one modifier is specified, ``.center`` is applied by default.
The first modifier refers to the position where the dropdown is placed:
- ``.bottom``
- ``.left``
- ``.right``
- ``.top``
The second modifier refers to the alignment of the dropdown with the trigger element:
- ``.bottom`` and ``.top`` positions can have ``.left`` | ``.center`` | ``.right``
- ``.right`` and ``.left`` positions can have ``.top`` | ``.center`` | ``.bottom``
```html
Show list
```
## Parameters
- ``id`` (__required__) is the *unique id* that *must* be assigned to the trigger element which links it to the dropdown element.
- ``modifiers`` contains the *position* and *alignment*, it is generally used to programmatically override the native modifiers.
```js
{
right: true,
center: true,
}
```
- ``scrollableContentClassName`` (__suggested__) is the class assigned to the wrapper element containing the main content within the dropdown, read [here](#behaviour) for more info on how it is used and why it would be better to set this.
```html
Show list
- User 1
- User 2
- User 3
```
- ``otherScrollableContentClassNames`` is the list of class names within the dropdown that are allowed to scroll.
- ``isReady`` is a *boolean* used to hold the directive hook *inserted* until the consumer is ready, the default is set to ``true``.
- ``arrow`` is a *boolean* used to show/hide the arrow between the trigger and the dropdown, the default is set to ``false``.
- ``arrowColor`` contains an *hexadecimal* used to set the color of the arrow next to the dropdown, the default is set to ``#fff``.
- ``zIndex`` is a *number* that specifies that stack order of the dropdown and its arrow, the default is set to ``9999``.
- ``offsetFromTrigger`` is a *number* that specifies the distance in pixels from where the dropdown is going to be rendered, the default is set to ``0``.
- ``onOpen`` is a *function* that runs at the opening of the dropdown.
- ``onClose`` is a *function* that runs on closing of the dropdown.
- ``keepOtherDropdownsOpen`` is a *boolean* that keeps the other dropdowns within the viewport opened when the trigger element action happens, the default is set ``false``.
- ``keepDropdownsOpenOnUIEvent`` is a *boolean* that keeps every dropdown within the viewport opened if a scroll or resize event has been triggered, the default is set ``true``.
- ``openOnlyProgrammatically`` is a *boolean* used to disable the trigger element action that opens the dropdown. If set to ``true``, the dropdown can be opened only [programmatically](#methods).
- ``allowTopCollocation`` is a *boolean* used to enable/disable the top position, the default is set to ``true``.
- ``allowBottomCollocation`` is a *boolean* used to enable/disable the bottom position, the default is set to ``true``.
- ``allowLeftCollocation`` is a *boolean* used to enable/disable the left position, the default is set to ``true``.
- ``allowRightCollocation`` is a *boolean* used to enable/disable the right position, the default is set to ``true``.
## Behaviour
Most of the time the dropdown is opened at the position set. However, there might be some scenarios where the space available within the viewport is simply not enough. So, the directive runs automatically a simulation, either to find the area within the viewport with the most available space or if an overflow to the content of the dropdown could be applied.
In order to prioritize the overflow of the content, the ``scrollableContentClassName`` parameter must be set. Instead, ``allowTopCollocation``, ``allowBottomCollocation``, ``allowLeftCollocation`` or ``allowRightCollocation`` parameters are used to restrict the positions to look for finding the areas with the most available space.
In order to ensure the dropdown is always placed next to the trigger element, the directive hides and re-paints it every time a scroll or a resize of the viewport happens.
## Methods
- ``open()`` is used to open the dropdown.
- ``close()`` is used to close the dropdown.
- ``closeOthers()`` is used to close every dropdown within the viewport except the current one.
- ``closeAll()`` is used to close every dropdown within the viewport.
- ``recalculatePosition()`` is used to re-calculate the position of the dropdown within the viewport.
- ``isOpen()`` is used to check if the current dropdown is showing.
This is an example of how the methods above can be executed:
```js
updateDropdownPosition() {
this.$refs.customDropdown.recalculatePosition();
},
```
```html
Show list
```