Field

标签、控件和错误信息的封装。

浏览器: Chrome 123+Firefox 121+Safari 17.5+
层级: 0
压缩后大小: 668 B
强制布局预算: 0 ms
axe 预算: 0
支持 SSR: 是
公开契约: 测试环境

交互示例

Field

Default

Name

Your display name

Invalid

Enter a valid email address

Password

Use at least eight characters.

Message

Up to 500 characters.

Disabled

Account ID

Read only

Workspace

React

CSS

Tailwind

import { Field } from "@gunkin/uiify";

export default function Example() {
  return (
    <Field.Root className="" id="email" required>
      <Field.Label className="" fieldId="email" required>
        Email
      </Field.Label>
      <Field.Control className="" fieldId="email" required as="input" type="email" />
      <Field.Description className="" fieldId="email">
        We will only use this for account notices.
      </Field.Description>
      <Field.Error className="" fieldId="email">
        Enter a valid email address.
      </Field.Error>
    </Field.Root>
  );
}

/* Text fields — Input and Textarea share the same surface. Invalid state keys
   off the [data-invalid] attribute the components emit. Textarea autosize uses
   the native field-sizing (Chrome 123+) when the component sets data-autosize. */

@layer components {
  :where([data-uiify-input], [data-uiify-textarea]) {
    display: block;
    inline-size: 100%;
    max-inline-size: 24rem;
    padding-block: var(--space-sm);
    padding-inline: var(--space-md);
    border: var(--border-width) solid var(--input);
    border-radius: var(--radius-md);
    corner-shape: squircle;
    background-color: var(--card);
    color: var(--foreground);
    font-size: var(--uiify-control-text);
    line-height: var(--leading-normal);
    transition: var(--transition-colors);
  }

  :where([data-uiify-input], [data-uiify-textarea])::placeholder {
    color: var(--muted-foreground);
  }

  :where([data-uiify-input], [data-uiify-textarea]):focus-visible {
    border-color: var(--primary);
  }

  :where([data-uiify-input], [data-uiify-textarea]):disabled,
  :where([data-uiify-input], [data-uiify-textarea])[data-disabled] {
    opacity: 0.5;
    cursor: not-allowed;
  }

  :where([data-uiify-input], [data-uiify-textarea])[data-invalid],
  :where([data-uiify-input], [data-uiify-textarea]):user-invalid {
    border-color: var(--destructive);
  }

  :where([data-uiify-input], [data-uiify-textarea])[data-invalid]:focus-visible {
    outline-color: var(--destructive);
  }

  [data-uiify-textarea] {
    min-block-size: 4lh;
    resize: block;
  }

  [data-uiify-textarea][data-autosize] {
    field-sizing: content;
    resize: none;
  }

  [data-uiify-field] {
    display: grid;
    gap: var(--space-sm);
    inline-size: 100%;
    max-inline-size: 24rem;
  }

  [data-uiify-field] [data-part="label"] {
    color: var(--foreground);
    font-size: var(--text-sm);
    font-weight: var(--weight-medium);
    line-height: var(--leading-normal);
  }

  [data-uiify-field] [data-part="label"][data-required]::after {
    content: " *";
    color: var(--destructive);
  }

  [data-uiify-field] [data-part="description"] {
    margin: 0;
    color: var(--muted-foreground);
    font-size: var(--text-xs);
    line-height: var(--leading-normal);
  }

  [data-uiify-field] [data-part="error"] {
    margin: 0;
    color: var(--destructive);
    font-size: var(--text-xs);
    line-height: var(--leading-normal);
  }

  /* Shared presence fade when an error message is mounted. */
  @media (prefers-reduced-motion: no-preference) {
    [data-uiify-field] [data-part="error"] {
      transition: opacity var(--duration-fast) var(--ease-out);
    }

    @starting-style {
      [data-uiify-field] [data-part="error"] {
        opacity: 0;
      }
    }
  }
}

import { Field } from "@gunkin/uiify";

export default function Example() {
  return (
    <Field.Root
      className={
        "grid gap-sm [inline-size:100%] [max-inline-size:24rem] [&_[data-part=label]]:text-foreground [&_[data-part=" +
        "label]]:text-sm [&_[data-part=label]]:font-[number:var(--weight-medium)] [&_[data-part=label]]:[line-height" +
        ":var(--leading-normal)] [&_[data-part=label][data-required]::after]:content-[\"_*\"] [&_[data-part=label][dat" +
        "a-required]::after]:text-destructive [&_[data-part=description]]:m-0 [&_[data-part=description]]:text-muted" +
        "-foreground [&_[data-part=description]]:text-xs [&_[data-part=description]]:[line-height:var(--leading-norm" +
        "al)] [&_[data-part=error]]:m-0 [&_[data-part=error]]:text-destructive [&_[data-part=error]]:text-xs [&_[dat" +
        "a-part=error]]:[line-height:var(--leading-normal)] motion-safe:[&_[data-part=error]]:[transition:opacity_va" +
        "r(--duration-fast)_var(--ease-out)] motion-safe:starting:[&_[data-part=error]]:opacity-0"
      }
      id="email"
      required
    >
      <Field.Label
        className={
          "text-foreground text-sm font-[number:var(--weight-medium)] [line-height:var(--leading-normal)] data-[requ" +
          "ired]:after:content-[\"_*\"] data-[required]:after:text-destructive"
        }
        fieldId="email"
        required
      >
        Email
      </Field.Label>
      <Field.Control
        className="
          focus-visible:[outline:none]
          focus-visible:[box-shadow:0_0_0_var(--ring-width)_color-mix(in_oklch,_var(--ring)_16%,_transparent)] block
          [inline-size:100%] [max-inline-size:24rem] py-sm px-md border-[length:var(--border-width)] border-solid
          border-input rounded-md [corner-shape:squircle] bg-card text-foreground [font-size:var(--uiify-control-text)]
          [line-height:var(--leading-normal)] [transition:var(--transition-colors)] placeholder:text-muted-foreground
          focus-visible:border-primary disabled:opacity-50 disabled:cursor-not-allowed data-[disabled]:opacity-50
          data-[disabled]:cursor-not-allowed data-[invalid]:border-destructive user-invalid:border-destructive
          data-[invalid]:focus-visible:outline-destructive
        "
        fieldId="email"
        required
        as="input"
        type="email"
      />
      <Field.Description
        className="m-0 text-muted-foreground text-xs [line-height:var(--leading-normal)]"
        fieldId="email"
      >
        We will only use this for account notices.
      </Field.Description>
      <Field.Error
        className="
          m-0 text-destructive text-xs [line-height:var(--leading-normal)] motion-safe:transition-opacity
          motion-safe:starting:opacity-0
        "
        fieldId="email"
      >
        Enter a valid email address.
      </Field.Error>
    </Field.Root>
  );
}

/* app.css */

@layer reset, ui, app, tokens, base, demo, components, utilities, theme;

@import "@gunkin/uiify/styles/reset";

@import "@gunkin/uiify/components/behavior.css";

@import "@gunkin/uiify/styles/tokens";

@import "@gunkin/uiify/styles/tailwind";

@import "tailwindcss/utilities.css";

@theme { --spacing: 0.25rem; --font-weight-normal: 400; --font-weight-medium: 500; --font-weight-semibold: 600; --font-weight-bold: 700; }

@source inline('grid gap-sm [inline-size:100%] [max-inline-size:24rem] [&_[data-part=label]]:text-foreground [&_[data-part=label]]:text-sm [&_[data-part=label]]:font-[number:var(--weight-medium)] [&_[data-part=label]]:[line-height:var(--leading-normal)] [&_[data-part=label][data-required]::after]:content-["_*"] [&_[data-part=label][data-required]::after]:text-destructive [&_[data-part=description]]:m-0 [&_[data-part=description]]:text-muted-foreground [&_[data-part=description]]:text-xs [&_[data-part=description]]:[line-height:var(--leading-normal)] [&_[data-part=error]]:m-0 [&_[data-part=error]]:text-destructive [&_[data-part=error]]:text-xs [&_[data-part=error]]:[line-height:var(--leading-normal)] motion-safe:[&_[data-part=error]]:[transition:opacity_var(--duration-fast)_var(--ease-out)] motion-safe:starting:[&_[data-part=error]]:opacity-0 text-foreground text-sm font-[number:var(--weight-medium)] [line-height:var(--leading-normal)] data-[required]:after:content-["_*"] data-[required]:after:text-destructive focus-visible:[outline:none] focus-visible:[box-shadow:0_0_0_var(--ring-width)_color-mix(in_oklch,_var(--ring)_16%,_transparent)] block py-sm px-md border-[length:var(--border-width)] border-solid border-input rounded-md [corner-shape:squircle] bg-card [font-size:var(--uiify-control-text)] [transition:var(--transition-colors)] placeholder:text-muted-foreground focus-visible:border-primary disabled:opacity-50 disabled:cursor-not-allowed data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed data-[invalid]:border-destructive user-invalid:border-destructive data-[invalid]:focus-visible:outline-destructive m-0 text-muted-foreground text-xs text-destructive motion-safe:transition-opacity motion-safe:starting:opacity-0');

@layer base { :root { --uiify-control-text: var(--text-sm); } @media (pointer: coarse) { :root { --uiify-control-text: var(--text-base); } } }

/* Authored animation and registered properties used by the Tailwind skin.
 * Visual rules belong in utility recipes; only at-rule definitions live here. */
@layer components {
  @keyframes uiify-presence-in {
    from {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@layer components {
  @keyframes uiify-presence-out {
    to {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@property --uiify-spinner-tail {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

@property --uiify-spinner-length {
  syntax: "<angle>";
  inherits: false;
  initial-value: 36deg;
}

@layer components {
  @keyframes uiify-spinner-rotate {
    to {
      transform: rotate(360deg);
    }
  }
}

@layer components {
  @keyframes uiify-spinner-orbit {
    0% {
      --uiify-spinner-tail: 0deg;
      --uiify-spinner-length: 36deg;
    }

    50% {
      --uiify-spinner-tail: 90deg;
      --uiify-spinner-length: 324deg;
    }

    100% {
      --uiify-spinner-tail: 360deg;
      --uiify-spinner-length: 36deg;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-pulse {
    50% {
      opacity: 0.45;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-shimmer {
    to {
      background-position: -200% 0;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-reveal {
    from {
      opacity: 0;
    }
    to {
      opacity: 1;
    }
  }
}

@property --candle-body-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-body-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-slot {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 100%;
}

@property --candle-wick-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-wick-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-x {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@property --line-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-prev-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-count {
  syntax: "<integer>";
  inherits: false;
  initial-value: 1;
}

@property --line-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@layer components {
  @keyframes uiify-otp-input-caret-blink {
    50% {
      opacity: 0;
    }
  }
}

API

`Field.Root`

属性	类型	默认值	说明
`id`*	`string`	—	每个组成部分均通过fieldId传回的稳定id，使标签、控件、描述和错误信息在服务端标记中相互连接。
`invalid`	`boolean`	`false`	将字段标为无效，并暴露data-invalid供样式使用。
`required`	`boolean`	`false`	将字段标为必填，并暴露data-required供样式使用。
`disabled`	`boolean`	`false`	将字段标为禁用，并暴露data-disabled供样式使用。
`name`	`string`	—	为API兼容而接受；name应设置在控件上，不会渲染到外层元素。
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	替换渲染元素，同时保留行为和无障碍连接关系。

`Field.Label`

属性	类型	默认值	说明
`fieldId`*	`string`	—	与Field.Root相同的id，用于解析指向控件的htmlFor。
`disabled`	`boolean`	`false`	将标签标为禁用，并暴露data-disabled供样式使用。
`required`	`boolean`	`false`	将标签标为必填，并暴露data-required供样式使用。

`Field.Control`

属性	类型	默认值	说明
`as`	`ElementType`	`"div"`	使用input、textarea、select或自定义控件。原生props、事件处理函数、style和ref均会转发。
`type / name / autoComplete / minLength / maxLength / pattern / readOnly`	`native control props`	—	输入框选项应设置在Field.Control上，包括type="password"。保留标准校验和FormData语义。
`fieldId`*	`string`	—	与Field.Root相同的id，用于解析控件id及其aria-labelledby和aria-describedby关联。
`disabled`	`boolean`	`false`	将原生disabled转发给input、textarea和select，并暴露data-disabled。
`invalid`	`boolean`	`false`	设置aria-invalid，并将错误信息加入控件的aria-describedby。
`required`	`boolean`	`false`	将原生required转发给input、textarea和select，并设置aria-required。
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	替换渲染元素，同时保留行为和无障碍连接关系。

`Field.Description`

属性	类型	默认值	说明
`fieldId`*	`string`	—	与Field.Root相同的id，用于解析控件所引用的描述id。
`disabled`	`boolean`	`false`	将描述标为禁用，并暴露data-disabled供样式使用。

`Field.Error`

属性	类型	默认值	说明
`fieldId`*	`string`	—	与Field.Root相同的id，用于解析控件无效时所引用的错误信息id。
`invalid`	`boolean`	`false`	是否渲染错误信息；为false时，该组成部分不渲染任何内容。

键盘

按键	操作
`Tab`	将焦点移入或移出控件
`Enter` / `Space`	获得焦点时激活（按钮类控件）

无障碍

尽可能使用语义化HTML。可在交互示例中检查渲染的标记；仅在原生元素无法满足需求时添加ARIA。

样式钩子

data-disabled

框架

样式

主题

语言

Field

交互示例

Field

Default

Invalid

Password

Message

Disabled

Read only

API

`Field.Root`

`Field.Label`

`Field.Control`

`Field.Description`

`Field.Error`

键盘

无障碍

样式钩子