https://github.com/flex-development/colors
:rainbow: a small library for coloring and styling messages
https://github.com/flex-development/colors
ansi browser cli color console node terminal
Last synced: 3 months ago
JSON representation
:rainbow: a small library for coloring and styling messages
- Host: GitHub
- URL: https://github.com/flex-development/colors
- Owner: flex-development
- License: bsd-3-clause
- Created: 2025-01-25T21:34:23.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-04-07T11:33:41.000Z (3 months ago)
- Last Synced: 2025-04-07T11:36:36.481Z (3 months ago)
- Topics: ansi, browser, cli, color, console, node, terminal
- Language: TypeScript
- Homepage: https://github.com/flex-development/colors
- Size: 2.45 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# \:rainbow: colors
[](https://github.com/flex-development/colors/releases/latest)
[](https://npmjs.com/package/@flex-development/colors)
[](https://codecov.io/github/flex-development/colors)
[](https://github.com/voxpelli/badges-cjs-esm)
[](LICENSE.md)
[](https://conventionalcommits.org)
[](https://typescriptlang.org)
[](https://vitest.dev)
[](https://yarnpkg.com)
Colorize messages in the terminal and browser
## Contents
- [What is this?](#what-is-this)
- [Features](#features)
- [Install](#install)
- [Use](#use)
- [API](#api)
- [`colors`](#colors)
- [`createColors([options])`](#createcolorsoptions)
- [`isColorSupported`](#iscolorsupported)
- [`stripAnsi(value[, toString])`](#stripansivalue-tostring)
- [Types](#types)
- [`ColorConfig`](#colorconfig)
- [`ColorConfigs`](#colorconfigs)
- [`ColorFunction`](#colorfunction)
- [`ColorFunctions`](#colorfunctions)
- [`Color`](#color)
- [`ColorizerOptions`](#colorizeroptions)
- [`Colors`](#colors-1)
- [`ToString`](#tostring)
- [Contribute](#contribute)
## What is this?
This is a small, but useful, library for creating colorful messages in the terminal and browser consoles that
support ANSI colors.
### Features
- `FORCE_COLOR`, [`NO_COLOR`][no-color], and `NODE_DISABLE_COLORS` friendly
- automatic color support detection
- no dependencies
- [typescript][] support
## Install
This package is [ESM only][esm].
In Node.js with [yarn][]:
```sh
yarn add @flex-development/colors
```
See Git - Protocols | Yarn
for details regarding installing from Git.
In Deno with [`esm.sh`][esmsh]:
```ts
import { colors } from 'https://esm.sh/@flex-development/colors'
```
In browsers with [`esm.sh`][esmsh]:
```html
import { createColors } from 'https://esm.sh/@flex-development/colors'
```
## Use
```ts
import c from '@flex-development/colors'
console.log(c.red(c.bold('Hello World!')))
```
## API
This package exports the following identifiers:
- [`colors`](#colors)
- [`createColors`](#createcolorsoptions)
- [`isColorSupported`](#iscolorsupported)
- [`stripAnsi`](#stripansivalue-tostring)
The default export is [`colors`](#colors).
### `colors`
([`Colors`](#colors-1)) The default colorizer.
### `createColors([options])`
Create a colorizer.
#### Parameters
- `options` ([`ColorizerOptions`](#colorizeroptions) | `boolean`, optional) —
boolean indicating if color output should be enabled, or an options object to create a custom colorizer
- **default**: [`isColorSupported()`](#iscolorsupported)
#### Returns
([`Colors`](#colors-1)) Colorizer object
### `isColorSupported`
Check if color output is supported.
#### Returns
(`boolean`) `true` if color output is supported, `false` otherwise
### `stripAnsi(value[, toString])`
Remove ANSI escape codes from `value`.
#### Parameters
- `value` (`unknown`) — the string or value to remove escape codes from
- `toString` ([`ToString`](#tostring), optional) — convert `value` to a string
- **default**: `String`
#### Returns
(`string`) Stringified `value` with ANSI escape codes removed
## Types
This package is fully typed with [TypeScript][].
### `ColorConfig`
List, where the first value is the numeric code for an ANSI escape sequence, and the second is the numeric code for the
reset sequence. The last value is an optional replacement for the reset sequence (used in complex cases to nest styles
without breaking existing color sequences).
```ts
type ColorConfig = [
open: number,
close: number,
replace?: string | null | undefined
]
```
### `ColorConfigs`
Record, where each key is a [`Color`](#color) and each value is the configuration for a color function.
```ts
type ColorConfigs = Record
```
### `ColorFunction`
Colorize `value` (TypeScript interface).
#### Parameters
- `value` (`unknown`) — the thing to colorize
#### Properties
- `close` (`string`) — reset sequence
- `open` (`string`) — sequence used to set colors
- `replace` (`string`, optional) — reset sequence replacement
#### Returns
(`string`) Colorized string `value`
### `ColorFunctions`
Registry of color functions (TypeScript interface).
### `Color`
Union of color names.
```ts
type Color = keyof ColorFunctions
```
To register custom colors, augment [`ColorFunctions`](#colorfunctions). They will be added to this union automatically.
```ts
declare module '@flex-development/colors' {
interface ColorFunctions {
blink: ColorFunction
}
}
```
### `ColorizerOptions`
Options for creating a colorizer (TypeScript interface).
#### Properties
- `color` (`boolean`, optional) — color output enabled?
- `colors` ([`Partial`](#colorconfigs), optional) — color function config map
### `Colors`
> also exported as `Colorizer`
A colorizer (TypeScript interface).
Colorizers contain [`Color`](#color) functions. Each function corresponds to a terminal color or style. The `color`
property is an accessor that can be used to disable or enable color output.
#### Extends
- [`ColorFunctions`](#colorfunctions)
#### Properties
- `get color(): boolean` — color output enabled?
- `set color(color: boolean | null | undefined)` - enable or disable color output\
👉 **note**: color output will be disabled if not supported
- `supported` (`boolean`) — color output supported? (`readonly`)
### `ToString`
Convert `value` to a string (TypeScript type).
#### Parameters
- `value` (`unknown`) — the thing to stringify
#### Returns
(`string`) Stringified `value`
## Contribute
See [`CONTRIBUTING.md`](CONTRIBUTING.md).
This project has a [code of conduct](./CODE_OF_CONDUCT.md). By interacting with this repository, organization, or
community you agree to abide by its terms.
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh
[no-color]: https://no-color.org
[typescript]: https://www.typescriptlang.org
[yarn]: https://yarnpkg.com