# Float label input

A text field whose label sits inside it while it is empty and rises to its top on focus or once it is filled. The label is always visible and always the field's name (a real `<label for>`), never a placeholder: a `placeholder` you pass shows only once the label has risen, as an example of the value ("name@company.com"). Takes `Input`'s props, so it goes inside a `Field` like any input; give it `label` there too or leave Field's `label` for a heading.

Right to left, the label sits at the right, by logical insets.

- Registry name: `float-label-input` (`@candor/float-label-input`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/float-label-input

## Install

```bash
npx candor-ui add float-label-input
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/float-label-input`.
It brings in: input, merge-refs, motion, tokens, utils.

## Example

```tsx
"use client"

import * as React from "react"
import { FloatLabelInput } from "@/components/candor/ui/float-label-input"

// The label sits inside the empty field and rises on focus or once filled; it is always the field's name. The
// placeholder is an example of the value and shows only once the label is up.
export default function Example() {
  const [email, setEmail] = React.useState("")
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <FloatLabelInput label="Work email" type="email" autoComplete="email" placeholder="name@company.com" value={email} onChange={(e) => setEmail(e.target.value)} />
      <FloatLabelInput label="Team" defaultValue="Customer success" />
    </div>
  )
}
```

## <FloatLabelInput>

Props:

- `label: string`: The field's name, shown inside it while empty and above its value once focused or filled. Required: it is the label.
- `placeholder?: string | undefined`: An example of the value, shown only once the label has risen (never in place of the label).

Also takes the props of `Omit<React.ComponentProps<typeof Input>, "children">`.

## Motion

- **label** (move): The label rises to the field's top on focus or once it is filled, and drops back when the field is left empty; one filled at the first draw starts up, with nothing moving.

Set with `--cd-motion-float-label-input-<moment>-*` in your brand file; the families are in the design reference.

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.