feat: add label/value object support for Select options, streamlines normalization

[Copilot]

Enables human-readable labels for Select option values, particularly useful when values are hex codes or other technical representations.

Changes

Core logic (select-plugin.ts):

• Detect arrays of {value, label} objects by checking first element
• Extract values and labels separately; fallback to value as label when label is missing
• Fixed array mutation bug where options array was incorrectly modified
• Updated comment to document support for array of {value, label} objects

Type definitions:

• Added SelectOption<T> type to select-types.ts and public.ts
• Extended SelectSettings to accept SelectOption<U>[]

Examples (Select.stories.tsx):

• Added ValueLabelObjects story demonstrating hex colors with friendly names

Usage

// Before: labels and values were coupled
useControls({
  icon: { options: { none: '', IconA, IconB } }  // Keys as labels
})

// After: labels and values are independent
useControls({
  color: {
    options: [
      { value: '#f00', label: 'red' },
      { value: '#0f0', label: 'green' },
      { value: '#00f', label: 'blue' }
    ]
  }
})

Backward compatible with existing array and object formats.

Demo

Labels display in the dropdown while hex color values are returned.

• Fixes Feature request: Allow label for options bindings? #551

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Feature request: Allow label for options bindings?</issue_title>
<issue_description>Rather than always have to see the actual values for a multi-value selection, it'd be great if one could specify per-value labels. Maybe along the lines of this:

const colorPicker = useControls({
  options: [
    { value: '#f00', label: 'red' },
    { value: '#0f0', label: 'green' },
    { value: '#00f', label: 'blue' }
  ],
  value: '#f00'
});

In my current use case I actually want the values to be JavaScript function objects, and I want to make human-readable labels for them.</issue_description>

<agent_instructions>User wants to be able to pass options as a value/label object.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@gsimone Want to make a PR @danfuzz ?

• Fixes Feature request: Allow label for options bindings? #551

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[changeset-bot]

⚠️ No Changeset found

Latest commit: ba22628

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
leva	Ready	Preview	Comment	Nov 3, 2025 10:00pm

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit ba22628:

Sandbox	Source
leva-minimal	Configuration
leva-busy	Configuration
leva-scroll	Configuration
leva-advanced-panels	Configuration
leva-ui	Configuration
leva-theme	Configuration
leva-transient	Configuration
leva-plugin-plot	Configuration
leva-plugin-bezier	Configuration
leva-plugin-spring	Configuration
leva-plugin-dates	Configuration
leva-custom-plugin	Configuration

[gsimone]

@copilot This is out of scope

[Copilot]

Removed the ValueLabelObjectsWithFunctions story in commit 5579ffe. The ValueLabelObjects story remains to demonstrate the new API.

[gsimone]

~

[gsimone]

@copilot Fix the comments and add a story for the new api

[Copilot]

@copilot Fix the comments and add a story for the new api

Fixed the comment in select-plugin.ts to document array of {value, label} objects format, and the ValueLabelObjects story demonstrates the new API in commit 5579ffe.

[Copilot]

Pull Request Overview

This PR enhances the Select input component to support a new {value, label} object array format for options, replaces the v8n validation library with Zod, and adds comprehensive test coverage using Vitest.

• Adds support for [{ value: T, label?: string }] format for select options
• Migrates validation from v8n to Zod for better type safety and clearer error messages
• Introduces Vitest 4.0.6 for testing with 361 lines of comprehensive test coverage

Reviewed Changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds [email protected] and [email protected] dependencies with related packages
packages/leva/package.json	Adds zod@^4.1.12 as a dependency
package.json	Adds vitest@^4.0.6 as a dev dependency
packages/leva/src/types/public.ts	Updates SelectInput types to support new SelectOption format
packages/leva/src/plugins/Select/select-types.ts	Adds SelectOption type definition and updates SelectSettings
packages/leva/src/plugins/Select/select-plugin.ts	Replaces v8n with Zod validation and implements new option format handling
packages/leva/src/plugins/Select/select-plugin.test.ts	Adds comprehensive test coverage for all select plugin functions
packages/leva/src/types/public.test.ts	Adds type tests for the new value/label object format
packages/leva/stories/inputs/Select.stories.tsx	Updates stories with better documentation and new ValueLabelObjects example
packages/leva/stories/advanced/Busy.stories.tsx	Fixes deprecated array-in-array option format

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

packages/leva/src/plugins/Select/select-plugin.ts:38

• Unused variable allUsecases.

const allUsecases = z.union([arrayOfPrimitivesSchema, keyAsLabelObjectSchema, arrayOfValueLabelObjectsSchema])

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The allUsecases schema is defined but never used in the code. Consider removing this unused variable or utilizing it if it was intended for validation purposes.