> ## Documentation Index
> Fetch the complete documentation index at: https://luau.limerence.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Colorpicker

> Pick a color or gradient, optionally with transparency and animation.

Also has everything from [ElementHandle](/ui/classes/element-handle).

Lets the user pick a color or gradient, optionally with transparency.

|                  |                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------- |
| **Picked value** | `Color3` or `ColorSequence` (+ transparency, rotation, animation, speed when enabled) |
| **Created by**   | [Section:AddColorpicker](/ui/classes/section#addcolorpicker)                          |

## Two kinds of value

There are two kinds of value to think about:

* **What the user picked**: the static color or gradient they chose, saved to their config. Read with `Peek*`, subscribe with `OnChange`.
* **What you should draw right now**: the same color, but if they enabled an animation it changes every frame. Read with `Get*`, subscribe with `OnUpdate`.

***

## GetColor

```luau theme={null}
picker:GetColor(): Color3
```

A single `Color3` to draw right now. If they picked a gradient, you get its first color.

***

## GetGradient

```luau theme={null}
picker:GetGradient(): ColorSequence
```

The current `ColorSequence`. Single colors are wrapped as a one-stop gradient.

***

## GetTransparency

```luau theme={null}
picker:GetTransparency(): number
```

`0..1`. `0` if the picker doesn't have a transparency slider.

***

## GetRotation

```luau theme={null}
picker:GetRotation(): number
```

Gradient rotation in degrees, including any animation.

***

## GetSnapshot

```luau theme={null}
picker:GetSnapshot(): ColorSnapshot
```

All four at once: `{ color, gradient, transparency, rotation }`. See [ColorSnapshot](/reference/types#colorsnapshot).

***

## OnUpdate

```luau theme={null}
picker:OnUpdate(callback: (snapshot: ColorSnapshot) -> ()): () -> ()
```

Runs every frame the displayed color changes: user picks and animation ticks. Your callback receives a snapshot.

<ResponseField name="returns" type="() -> ()">
  Unsubscribe function.
</ResponseField>

***

## OnChange

```luau theme={null}
picker:OnChange(callback: (picked: Color3 | ColorSequence) -> ()): () -> ()
```

Runs only when the user picks a new color. Doesn't fire on animation ticks.

***

## OnColorChange

```luau theme={null}
picker:OnColorChange(callback: (picked: Color3 | ColorSequence) -> ()): () -> ()
```

Same as `OnChange`.

***

## OnTransparencyChange

```luau theme={null}
picker:OnTransparencyChange(callback: (alpha: number?) -> ()): () -> ()
```

Runs only when the user changes the transparency slider.

***

## PeekColor

```luau theme={null}
picker:PeekColor(): Color3 | ColorSequence
```

The raw color the user picked, ignoring any animation.

***

## PeekTransparency

```luau theme={null}
picker:PeekTransparency(): number?
```

The transparency the user picked, or `nil` if the picker has no transparency slider.

***

## SetState

```luau theme={null}
picker:SetState(color: Color3 | ColorSequence): ()
```

Set the color or gradient (same as [SetValue](/ui/classes/element-handle#setvalue)).

***

## SetTransparency

```luau theme={null}
picker:SetTransparency(alpha: number): ()
```

`0` (opaque) to `1` (invisible).

***

## SetRotation

```luau theme={null}
picker:SetRotation(degrees: number): ()
```

Rotate the gradient.

***

## SetAnimation

```luau theme={null}
picker:SetAnimation(key: GradientAnimation): ()
```

Turn on an animation. Does nothing if it can't apply (e.g. shimmer on a single color).

| Animation   | Works on                                |
| ----------- | --------------------------------------- |
| `"none"`    | Anything. Turns animation off           |
| `"shimmer"` | Gradients only. Spins the gradient      |
| `"rainbow"` | Anything. Cycles through hues           |
| `"blink"`   | Pickers with a transparency slider only |

***

## SetSpeed

```luau theme={null}
picker:SetSpeed(multiplier: number): ()
```

Animation speed. `1` is normal.

## Example: paint a frame

```luau theme={null}
local cp = section:AddColorpicker("fill", "Fill", Color3.fromRGB(255, 100, 100), 0)

local function paint()
    local snap = cp:GetSnapshot()
    frame.BackgroundColor3 = snap.color
    frame.BackgroundTransparency = snap.transparency
end

paint()
cp:OnUpdate(paint)
```

## Example: only when the user picks something new

```luau theme={null}
cp:OnChange(function(picked)
    print("user picked", picked)
end)
```