Skip to content

Commit 965d2ff

Browse files
simeydotmesimeydotme
committed
add back readme
1 parent 118cddb commit 965d2ff

File tree

5 files changed

+256
-32
lines changed

5 files changed

+256
-32
lines changed

‎README.md‎

Lines changed: 170 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,196 @@
1-
# create-svelte
1+
<div align="center">
22

3-
Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
3+
<img src="public/svelte-range-slider-logo.svg"
4+
alt="Svelte Range Slider Logo" width="20%">
5+
</div>
46

5-
Read more about creating a library [in the docs](https://kit.svelte.dev/docs/packaging).
7+
<h1 align="center">
8+
Svelte Range Slider (with pips)
69

7-
## Creating a project
10+
<p>
11+
<a href="https://github.com/simeydotme/svelte-range-slider-pips/releases">
12+
<img src="https://img.shields.io/github/package-json/v/simeydotme/svelte-range-slider-pips/main?label=&color=%234A40D4&logo=github" alt="Code Version">
13+
</a>
14+
<a href="https://www.npmjs.com/package/svelte-range-slider-pips">
15+
<img src="https://img.shields.io/npm/v/svelte-range-slider-pips?color=%234A40D4&logo=npm&label=" alt="NPM version">
16+
<img src="https://img.shields.io/npm/dm/svelte-range-slider-pips?label=&color=%234A40D4" alt="NPM Downloads / Month">
17+
</a>
18+
</p>
19+
</h1>
820

9-
If you're seeing this, you've probably already done this step. Congrats!
21+
A reactive, accessible, multi-thumb, range slider with the ability to display "pips" or "notches" along the range.
22+
Importable as a ***svelte-component***, or able to be **used directly in any javascript application / framework**.
1023

11-
```bash
12-
# create a new project in the current directory
13-
npm create svelte@latest
24+
![Svelte Range Slider; focussed with pips and labels prop set](public/svelte-range-slider-screenshot.png)
1425

15-
# create a new project in my-app
16-
npm create svelte@latest my-app
17-
```
1826

19-
## Developing
2027

21-
Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
28+
| 📔🔍 | Docs | [Full Documentation & Examples](https://simeydotme.github.io/svelte-range-slider-pips/) |
29+
| :--: | -----: | :------ |
30+
| 📝⚙ | **REPL** | **[Svelte component demo](https://svelte.dev/repl/030797781fd64ad88302d1343f5b2c43?version=3)** |
31+
| ❤✒ | **Codepen** | **[Plain JS component demo](https://codepen.io/simeydotme/pen/KKNJdbK)** |
2232

23-
```bash
24-
npm run dev
33+
---
2534

26-
# or start the server and open the app in a new browser tab
27-
npm run dev -- --open
28-
```
35+
<br>
36+
37+
## Features
2938

30-
Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
39+
![Features of the range slider plugin (written below)](public/svelte-range-slider-features.png)
3140

32-
## Building
41+
- ✨ fully customisable, stylable & accessible
42+
- 👍🏽 multi-thumb
43+
- 🎚 range (min/max)
44+
- 🏷 floating labels
45+
- 📏 ruler notches
46+
- 🏷 labels for notches
47+
- 🧮 step function
48+
- 🖍 formatter
49+
- 🎭 animated
3350

34-
To build your library:
51+
## Install
52+
53+
Open your project and use the command line to install the package;
3554

3655
```bash
37-
npm run package
56+
yarn add svelte-range-slider-pips --dev # or
57+
npm install svelte-range-slider-pips --save-dev # if you prefer npm
3858
```
3959

40-
To create a production version of your showcase app:
60+
## Usage
4161

42-
```bash
43-
npm run build
62+
### In a svelte project
63+
64+
Assuming you have a Svelte app up and running;
65+
66+
```html
67+
<script>
68+
import RangeSlider from "svelte-range-slider-pips";
69+
</script>
70+
71+
<RangeSlider values={[50]} pips />
4472
```
4573

46-
You can preview the production build with `npm run preview`.
74+
### As a regular JS file
4775

48-
> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
76+
If you're not building a svelte-app, you can use the [`/dist/`
77+
version of the script `/dist/svelte-range-slider-pips.js`](dist/svelte-range-slider-pips.js) and include it
78+
with a regular `<script>` tag. This should even work with jQuery.
4979

50-
## Publishing
80+
```html
81+
<script src="./js/vendor/svelte-range-slider-pips.js" />
5182
52-
Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
83+
<div id="my-slider"></div>
5384
54-
To publish your library to [npm](https://www.npmjs.com):
85+
<script>
86+
var mySlider = new RangeSliderPips({
87+
target: document.querySelector("#my-slider"),
88+
props: { values: [50], pips: true }
89+
});
90+
</script>
91+
```
5592

56-
```bash
57-
npm publish
93+
### As a JS module
94+
95+
If you're building a bleeding-edge JS application (maybe Vue or React), you might
96+
want to use js imports (`import`)
97+
98+
```js
99+
import RangeSlider from "./node_modules/svelte-range-slider-pips/dist/svelte-range-slider-pips.mjs";
100+
101+
var mySlider = new RangeSlider({
102+
target: node, // js reference to a DOM element
103+
props: { values: [50], pips: true }
104+
});
58105
```
106+
107+
---
108+
109+
<br>
110+
111+
## Props (options)
112+
113+
### Slider props
114+
115+
prop | type | default | description
116+
-----|------|---------|-------------
117+
**values** | `Array` | `[50]` | Array of values to apply on the slider. Multiple values creates multiple handles. (_**note:** A slider with `range` property set can only have two values max_)
118+
**min** | `Number` | `0` | Minimum value for the slider _(should be `< max`)_
119+
**max** | `Number` | `100` | Maximum value for the slider _(should be `> min`)_
120+
**step** | `Number` | `1` | Every `nth` value to allow handle to stop at _(should be a positive value)_
121+
**range** | `Boolean`/`String` | `false` | Whether to style as a range picker. Use `range='min'` or `range='max'` for min/max variants
122+
**pushy** | `Boolean` | `false` | If `range` is `true`, then this boolean decides if one handle will push the other along
123+
**float** | `Boolean` | `false` | Set true to add a floating label above focussed handles
124+
**vertical** | `Boolean` | `false` | Make the slider render vertically (lower value on bottom)
125+
**pips** | `Boolean` | `false` | Whether to show pips/notches on the slider
126+
**pipstep** | `Number` | `1`/`10`/`20` | Every `nth` step to show a pip for. This has multiple defaults depending on `values` property
127+
**first** | `Boolean`/`String` | `false` | Whether to show a pip or label for the first value on slider. Use `first='label'` to show a label value
128+
**last** | `Boolean`/`String` | `false` | Whether to show a pip or label for the last value on slider. Use `last='label'` to show a label value
129+
**rest** | `Boolean`/`String` | `false` | Whether to show a pip or label for all other values. Use `rest='label'` to show a label value
130+
**all** | `Boolean`/`String` | `false` | Whether to show a pip or label for all values. Same as combining `first`, `last` and `rest`. Use `all='label'` to show a label value
131+
**prefix** | `String` | `""` | A string to prefix to all displayed values
132+
**suffix** | `String` | `""` | A string to suffix to all displayed values
133+
**reversed** | `Boolean` | `false` | Reverse the orientation of min/max
134+
**hoverable** | `Boolean` | `true` | Whether hover styles are enabled for both handles and pips/values
135+
**disabled** | `Boolean` | `false` | Determine if the slider is disabled, or enabled _(only disables interactions, and events)_
136+
**id** | `String` | `""` | Give the slider a unique ID for use in styling
137+
**ariaLabels** | `Array` | `[]` | Array of strings to use for the `aria-label` attribute on the handles.
138+
**formatter** | `Function` | `(v,i,p) => v` | A function to re-format values before they are displayed (`v = value, i = pip index, p = percent`)
139+
**handleFormatter** | `Function` | `formatter` | A function to re-format values on the handle/float before they are displayed. Defaults to the same function given to the `formatter` property (`v = value, i = handle index, p = percent`)
140+
**springValues** | `Object` | `{ stiffness: 0.15, damping: 0.4 }` | Svelte spring physics object to change the behaviour of the handle when moving
141+
**slider** | `Element` | `undefined` | DOM reference for binding to the main `<div />` of the component (`bind:slider='ref'`)
142+
143+
**[📔🔍 | Documentation for Options](https://simeydotme.github.io/svelte-range-slider-pips/en/options/)**
144+
<br>
145+
<br>
146+
147+
### Slider events (dispatched)
148+
149+
event | example | `event.detail` | description
150+
------|------------|--------|-------------
151+
**start** | `on:start={(e) => { ... }}` | `{ activeHandle: Integer, value: Float, values: Array }` | Event fired when the user begins interaction with the slider
152+
**change** | `on:change={(e) => { ... }}` | `{ activeHandle: Integer, startValue: Float, previousValue: Float, value: Float, values: Array }` | Event fired when the user changes the value; returns the previous value, also
153+
**stop** | `on:stop={(e) => { ... }}` | `{ activeHandle: Integer, startValue: Float, value: Float, values: Array }` | Event fired when the user stops interacting with slider; returns the beginning value, also
154+
155+
**[📔🔍 | Documentation for Events](https://simeydotme.github.io/svelte-range-slider-pips/en/events/)**
156+
157+
<br>
158+
<br>
159+
160+
## Styling
161+
162+
**Styling should mostly be done with CSS.**
163+
There's a [bunch of css variables for controlling the colors](https://simeydotme.github.io/svelte-range-slider-pips/#styling) of the elements.
164+
And the slider is fluid horizontally, with the size of things controlled by font-size. So you may change the `font-size` on the `.rangeSlider` base
165+
element to change the scale of everything.
166+
167+
If you require more fine control of the widths, heights, etc, then you may override the default css. This can be easier by using the `id` prop
168+
to give your slider a unique id.
169+
170+
Values of labels can be styled with CSS, and the format can be modified with the `formatter()` function prop. And animation of the handles is
171+
controlled by the `springValues` object prop.
172+
173+
**[📔🔍 | Documentation for Styling](https://simeydotme.github.io/svelte-range-slider-pips/en/styling/)**
174+
175+
<br>
176+
<br>
177+
178+
## Contribute
179+
180+
I am very happy to accept;
181+
182+
- 🌟 suggestions/requests for new features or changes
183+
- 🛠 pull-requests for bug fixes, or issue resolution
184+
- 🧪 help with creating a proper test-suite
185+
186+
[Read the CONTRIBUTING.md](./CONTRIBUTING.md)
187+
188+
---
189+
190+
## Support / Donate
191+
I'd be super excited if you find this project useful and wish to donate a small amount for my efforts!
192+
193+
| <img src="https://user-images.githubusercontent.com/2817396/149629283-6002944f-9253-4e35-917d-89b476deae4e.png" width=20> | [![£1 One Pound Donation](https://user-images.githubusercontent.com/2817396/149629980-08b9a952-bd6a-4c23-be78-05e3fd534352.png)](https://www.paypal.com/paypalme/simey/1) | [£1 GBP donation](https://www.paypal.com/paypalme/simey/1) |
194+
|--|--:|---------|
195+
| <img src="https://user-images.githubusercontent.com/2817396/149629283-6002944f-9253-4e35-917d-89b476deae4e.png" width=20> | [![£5 Five Pounds Donation](https://user-images.githubusercontent.com/2817396/149629994-3a99770c-d333-46e7-9818-ab6b18ad0202.png)](https://www.paypal.com/paypalme/simey/5) | [£5 GBP donation](https://www.paypal.com/paypalme/simey/5) |
196+
| <img src="https://user-images.githubusercontent.com/2817396/149629283-6002944f-9253-4e35-917d-89b476deae4e.png" width=20> | [![£10 Ten Pounds Donation](https://user-images.githubusercontent.com/2817396/149630000-95aa4234-ff67-4e7c-a7f4-ffd52f25e6d8.png)](https://www.paypal.com/paypalme/simey/10) | [£10 GBP donation](https://www.paypal.com/paypalme/simey/10) |

‎public/svelte-range-slider-features.png‎

122 KB
Loading

‎public/svelte-range-slider-logo.png‎

25.4 KB
Loading

‎public/svelte-range-slider-logo.svg‎

Lines changed: 86 additions & 0 deletions
Loading

‎public/svelte-range-slider-screenshot.png‎

3.1 KB
Loading

0 commit comments

Comments
 (0)