|
1 | | -<div align="center"> |
| 1 | +# create-svelte |
2 | 2 |
|
3 | | -<img src="test/public/svelte-range-slider-logo.svg" |
4 | | - alt="Svelte Range Slider Logo" width="20%"> |
5 | | -</div> |
| 3 | +Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte). |
6 | 4 |
|
7 | | -<h1 align="center"> |
8 | | - Svelte Range Slider (with pips) |
| 5 | +Read more about creating a library [in the docs](https://kit.svelte.dev/docs/packaging). |
9 | 6 |
|
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> |
| 7 | +## Creating a project |
20 | 8 |
|
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**. |
23 | | - |
24 | | - |
25 | | - |
26 | | - |
27 | | - |
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)** | |
32 | | - |
33 | | ---- |
34 | | - |
35 | | -<br> |
36 | | - |
37 | | -## Features |
38 | | - |
39 | | - |
40 | | - |
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 |
50 | | - |
51 | | -## Install |
52 | | - |
53 | | -Open your project and use the command line to install the package; |
| 9 | +If you're seeing this, you've probably already done this step. Congrats! |
54 | 10 |
|
55 | 11 | ```bash |
56 | | -yarn add svelte-range-slider-pips --dev # or |
57 | | -npm install svelte-range-slider-pips --save-dev # if you prefer npm |
58 | | -``` |
59 | | - |
60 | | -## Usage |
61 | | - |
62 | | -### In a svelte project |
63 | | - |
64 | | -Assuming you have a Svelte app up and running; |
| 12 | +# create a new project in the current directory |
| 13 | +npm create svelte@latest |
65 | 14 |
|
66 | | -```html |
67 | | -<script> |
68 | | - import RangeSlider from "svelte-range-slider-pips"; |
69 | | -</script> |
70 | | - |
71 | | -<RangeSlider values={[50]} pips /> |
| 15 | +# create a new project in my-app |
| 16 | +npm create svelte@latest my-app |
72 | 17 | ``` |
73 | 18 |
|
74 | | -### As a regular JS file |
75 | | - |
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. |
| 19 | +## Developing |
79 | 20 |
|
80 | | -```html |
81 | | -<script src="./js/vendor/svelte-range-slider-pips.js" /> |
| 21 | +Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server: |
82 | 22 |
|
83 | | -<div id="my-slider"></div> |
| 23 | +```bash |
| 24 | +npm run dev |
84 | 25 |
|
85 | | -<script> |
86 | | - var mySlider = new RangeSliderPips({ |
87 | | - target: document.querySelector("#my-slider"), |
88 | | - props: { values: [50], pips: true } |
89 | | - }); |
90 | | -</script> |
| 26 | +# or start the server and open the app in a new browser tab |
| 27 | +npm run dev -- --open |
91 | 28 | ``` |
92 | 29 |
|
93 | | -### As a JS module |
| 30 | +Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app. |
94 | 31 |
|
95 | | -If you're building a bleeding-edge JS application (maybe Vue or React), you might |
96 | | -want to use js imports (`import`) |
| 32 | +## Building |
97 | 33 |
|
98 | | -```js |
99 | | -import RangeSlider from "./node_modules/svelte-range-slider-pips/dist/svelte-range-slider-pips.mjs"; |
| 34 | +To build your library: |
100 | 35 |
|
101 | | -var mySlider = new RangeSlider({ |
102 | | - target: node, // js reference to a DOM element |
103 | | - props: { values: [50], pips: true } |
104 | | -}); |
| 36 | +```bash |
| 37 | +npm run package |
105 | 38 | ``` |
106 | 39 |
|
107 | | ---- |
| 40 | +To create a production version of your showcase app: |
108 | 41 |
|
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 |
| 42 | +```bash |
| 43 | +npm run build |
| 44 | +``` |
179 | 45 |
|
180 | | -I am very happy to accept; |
| 46 | +You can preview the production build with `npm run preview`. |
181 | 47 |
|
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 |
| 48 | +> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment. |
185 | 49 |
|
186 | | -[Read the CONTRIBUTING.md](./CONTRIBUTING.md) |
| 50 | +## Publishing |
187 | 51 |
|
188 | | ---- |
| 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/)). |
189 | 53 |
|
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! |
| 54 | +To publish your library to [npm](https://www.npmjs.com): |
192 | 55 |
|
193 | | -| <img src="https://user-images.githubusercontent.com/2817396/149629283-6002944f-9253-4e35-917d-89b476deae4e.png" width=20> | [](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> | [](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> | [](https://www.paypal.com/paypalme/simey/10) | [£10 GBP donation](https://www.paypal.com/paypalme/simey/10) | |
| 56 | +```bash |
| 57 | +npm publish |
| 58 | +``` |
0 commit comments