# `NeoFaker.Color`
[🔗](https://github.com/muzhawir/neo_faker/blob/main/lib/neo_faker/color.ex#L1)

Functions for generating random colors.

Provides utilities to generate random colors in various formats including
CMYK, HEX, HSL, HSLA, RGB, RGBA, and CSS keyword colors, with optional
W3C string formatting.

# `cmyk`
*since 0.8.0* 

```elixir
@spec cmyk(Keyword.t()) :: tuple() | String.t()
```

Generates a random CMYK color.

Returns a tuple `{cyan, magenta, yellow, black}` where each component is an
integer percentage from 0 to 100. Pass `format: :w3c` for a CSS string.

## Options

- `:format` - Output format. Either `nil` (tuple, default) or `:w3c` (CSS string).

## Examples

    iex> NeoFaker.Color.cmyk()
    {0, 25, 50, 100}

    iex> NeoFaker.Color.cmyk(format: :w3c)
    "cmyk(0%, 25%, 50%, 100%)"

# `hex`
*since 0.8.0* 

```elixir
@spec hex(Keyword.t()) :: String.t()
```

Generates a random HEX color string.

Returns a `#`-prefixed hex color. Defaults to six-digit format.

## Options

- `:format` - Digit length. One of `:six_digit` (default), `:three_digit`,
  `:four_digit`, or `:eight_digit`.

## Examples

    iex> NeoFaker.Color.hex()
    "#613583"

    iex> NeoFaker.Color.hex(format: :three_digit)
    "#365"

    iex> NeoFaker.Color.hex(format: :eight_digit)
    "#613583FF"

# `hsl`
*since 0.8.0* 

```elixir
@spec hsl(Keyword.t()) :: tuple() | String.t()
```

Generates a random HSL color.

Returns a `{hue, saturation, lightness}` tuple. Hue is in degrees (0–360);
saturation and lightness are integer percentages (0–100). Pass `format: :w3c`
for a CSS string.

## Options

- `:format` - Output format. Either `nil` (tuple, default) or `:w3c` (CSS string).

## Examples

    iex> NeoFaker.Color.hsl()
    {180, 50, 75}

    iex> NeoFaker.Color.hsl(format: :w3c)
    "hsl(180, 50%, 75%)"

# `hsla`
*since 0.8.0* 

```elixir
@spec hsla(Keyword.t()) :: tuple() | String.t()
```

Generates a random HSLA color.

Returns a `{hue, saturation, lightness, alpha}` tuple. Hue is in degrees (0–360),
saturation and lightness are integer percentages (0–100), and alpha is a float
between 0.0 and 1.0. Pass `format: :w3c` for a CSS string.

## Options

- `:format` - Output format. Either `nil` (tuple, default) or `:w3c` (CSS string).

## Examples

    iex> NeoFaker.Color.hsla()
    {180, 50, 75, 0.8}

    iex> NeoFaker.Color.hsla(format: :w3c)
    "hsla(180, 50%, 75%, 0.8)"

# `keyword`
*since 0.8.0* 

```elixir
@spec keyword(Keyword.t()) :: String.t()
```

Generates a random CSS keyword color name.

Returns a color name string such as `"blueviolet"` or `"purple"`. Supports
locale-specific color names (e.g. Indonesian via `locale: :id_id`).

## Options

- `:category` - Color category. One of `:all` (default), `:basic`, or `:extended`.
- `:locale` - Locale to use. Defaults to the application's configured locale.

## Examples

    iex> NeoFaker.Color.keyword()
    "blueviolet"

    iex> NeoFaker.Color.keyword(category: :basic)
    "purple"

    iex> NeoFaker.Color.keyword(locale: :id_id)
    "ungu"

# `random`
*since 0.8.0* 

```elixir
@spec random(Keyword.t()) :: tuple() | String.t()
```

Generates a random color in a randomly selected format.

With no options, picks uniformly among CMYK, HEX, HSL, HSLA, RGB, and RGBA.
Pass `format: :w3c` to restrict the pool to formats that support W3C strings
(excludes HEX), or any other `:format` value to pass it through to each
individual generator.

## Examples

    iex> NeoFaker.Color.random()
    {255, 128, 64}

    iex> NeoFaker.Color.random()
    "#613583"

# `rgb`
*since 0.8.0* 

```elixir
@spec rgb(Keyword.t()) :: tuple() | String.t()
```

Generates a random RGB color.

Returns a `{red, green, blue}` tuple where each component is an integer from
0 to 255. Pass `format: :w3c` for a CSS string.

## Options

- `:format` - Output format. Either `nil` (tuple, default) or `:w3c` (CSS string).

## Examples

    iex> NeoFaker.Color.rgb()
    {255, 128, 64}

    iex> NeoFaker.Color.rgb(format: :w3c)
    "rgb(255, 128, 64)"

# `rgba`
*since 0.8.0* 

```elixir
@spec rgba(Keyword.t()) :: tuple() | String.t()
```

Generates a random RGBA color.

Returns a `{red, green, blue, alpha}` tuple. RGB components are integers from
0 to 255; alpha is a float between 0.0 and 1.0. Pass `format: :w3c` for a
CSS string.

## Options

- `:format` - Output format. Either `nil` (tuple, default) or `:w3c` (CSS string).

## Examples

    iex> NeoFaker.Color.rgba()
    {255, 128, 64, 0.8}

    iex> NeoFaker.Color.rgba(format: :w3c)
    "rgba(255, 128, 64, 0.8)"

---

*Consult [api-reference.md](api-reference.md) for complete listing*