tinted
Version:
An interactive color wheel for the browser
141 lines (103 loc) • 6.62 kB
Markdown
# Tinted
Tinted is a color harmony wheel. It helps you choose color combinations that create pleasing contrasts and feel harmonious.
[Demo](https://zposten.github.io/tinted)
## Install
```bash
# Install with yarn
yarn add tinted
# Or install with NPM
npm i tinted
```
## Usage
```html
<div class="my-color-wheel">
<svg class="tinted-wheel"></svg>
<div class="tinted-palette"></div>
</div>
```
```scss
@use 'tinted/wheel';
@use 'tinted/palette';
.my-color-wheel {
display: flex;
flex-direction: column;
align-items: center;
margin: auto;
max-width: 400px;
}
```
```js
import {TintedWheel, TintedPalette} from 'tinted'
let colorWheel = new TintedWheel({
container: document.querySelector('.tinted-wheel'),
colorWheelImage: './wheel.png',
})
let palette = new TintedPalette({
container: document.querySelector('.tinted-palette'),
colorWheel: colorWheel,
})
colorWheel.dispatch.on('bind-data.main', data => palette.render(data))
colorWheel.dispatch.on('markers-updated.main', () => {
palette.onColorValuesChanged()
})
colorWheel.bindData()
```
A few things to note:
- The wheel can be used without the palette, but it is recommended to use them together.
- To make these abbreviated `@use` statements work, you will need to add `node_modules` to SASS' `--load-path` or sass-loader's `includePaths`. Alternatively, you could just path into `node_modules` explicitly.
- If you're not using SASS in your project, we do provide compiled CSS files in the `dist` folder.
## Custom Colors
You can initialize Tinted with a custom color set:
```js
let colors = [
'red',
'#0ff',
{r: 0, g: 255, b: 0},
{h: 220, s: 1, v: 1},
{h: 300, s: 1, l: 0.5},
'hsl(0, 100%, 50%)',
]
let wheel = new TintedWheel(options)
wheel.bindData(colors)
```
## Components
### TintedWheel
The color harmony wheel for the user to make a selection of colors.
#### Options
| Name | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `container` | A DOM node or CSS selector for the `<svg>` element that the wheel should be created inside of |
| `colorWheelImage` | A URI to a color HSV color wheel image to use |
| `radius` | The radius of the wheel in SVG coordinate units |
| `markerWidth` | The diameter of the markers used to select colors on the wheel in SVG coordinate units |
| `markerOutlineWidth` | The width of the outline of the color marker in SVG coordinate units |
| `margin` | The distance between the border of the `<svg>` and the circle of the wheel in SVG coordinate units |
| `initRoot` | The color that should initially be used to select other harmony colors |
| `initMode` | The initial mode the color wheel is in |
| `baseClassName` | The prefix for the class names for all generated elements. Overriding this will cause all provided CSS to no longer work |
#### Methods
| Name | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bindData(userData)` | It is mandatory to invoke this method. Pass in either an array of color-like values, or the number of colors to initially display. Default to 5 colors |
| `setMode(mode)` | Set the mode of the wheel. Must be a value from the exported `colorModes` object |
| `setHarmony()` | Based on the current root marker and the current mode, set the values of the other markers to be in harmony |
| `isInMode(mode): boolean` | Returns true if the wheel is in that mode |
### TintedPalette
A palette of colors to display the user's chosen values from the `TintedWheel`. For each color it:
- Allows the user to change the value (or brightness -- "V" in the HSV color model) of the color
- Displays the hex string value of the color
#### Options
| Name | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `container` | A DOM node or CSS selector for the element that the palette should be created inside of |
| `colorWheel` | The `TintedColorWheel` object to base the palette off of |
| `baseClassName` | The prefix for the class names for all generated elements. Overriding this will cause all provided CSS to no longer work |
#### Methods
| Name | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `constructor(options)` | Constructor |
| `render(data)` | Create or update the number of colors in the palette based on data from the wheel |
| `onColorValuesChanged()` | Update the color values for the existing number of colors, passing in the current mode the wheel is in |
## Styling
Feel free to override any of the default styling as you please.
Out of the box, tinted supports a color scheme for a light and dark background, defaulting to the light background. To change it to expect a dark background, add a `tinted--dark` class to a parent element of the wheel and/or palette.