TagsField Campo de Tags - Docs - Artefact

TagsField Campo de Tags

Forms

Detecção automática inteligente

Um componente que permite aos usuários inserir várias tags como uma lista, com as mesmas convenções de rótulo / texto de ajuda / texto de erro do Field.

Uso

Skills

React

Hono

Pressione Enter para adicionar uma tag

import { TagsField } from "../components/ui";

export default function MyPage() {
  return (
    <TagsField
      label="Skills"
      helperText="Pressione Enter para adicionar uma tag"
      defaultValue={["React", "Hono"]}
      onValueChange={(details) => console.log(details.value)}
    />
  );
}

Comportamento

Enter confirma o texto digitado como uma nova tag (duplicatas são ignoradas) e limpa o campo.
Backspace com o campo vazio remove a última tag.
Clicar no botão de remover de uma tag (renderizado por Items) remove aquela tag específica.
Clicar em qualquer lugar do controle que não seja uma tag foca o campo de entrada.

Variantes e tamanhos

<TagsField variant="subtle" size="lg" defaultValue={["React"]} />

Composição

As props padrão label/helperText/errorText cobrem a maioria dos casos, mas as partes internas também são exportadas para layouts personalizados:

import { TagsField } from "../components/ui";

<TagsField.Root defaultValue={["React", "Hono"]}>
  <TagsField.Label>Skills</TagsField.Label>
  <TagsField.Control>
    <TagsField.Items />
    <TagsField.Input placeholder="Add a skill…" />
  </TagsField.Control>
  <TagsField.ClearTrigger>Clear all</TagsField.ClearTrigger>
  <TagsField.HiddenInput name="skills" />
</TagsField.Root>;

Construtor de páginas CMS

Este componente está disponível como um bloco tagsField no Construtor de páginas (content/pages/*.json):

{
  "type": "tagsField",
  "label": "Amenities",
  "defaultValue": ["WiFi", "Fireplace", "Hot Tub"]
}

Propriedades

Prop	Type	Default	Description
`value`	`string[]`	-	Tags controladas (força o modo interativo).
`defaultValue`	`string[]`	-	Tags iniciais.
`inputValue`	`string`	-	Valor controlado do campo de texto (força o modo interativo).
`defaultInputValue`	`string`	-	Valor inicial do campo de texto.
`label`	`Child`	-	Rótulo do campo.
`helperText`	`Child`	-	Texto de ajuda exibido abaixo das tags.
`errorText`	`Child`	-	Texto de erro exibido quando `invalid` está definido.
`invalid`	`boolean`	-	Força o estado inválido, exibindo `errorText`.
`disabled`	`boolean`	-	Desativa o campo de entrada e os botões de remover/limpar.
`readOnly`	`boolean`	-	Oculta o campo de texto, impedindo a adição de novas tags.

| size | `"xs" \ | "sm" \ | "md" \ | "lg"` | "md" | Tamanho do controle. |

| dir | `"ltr" \ | "rtl"` | - | Direção do texto. |

| onValueChange | (details: { value: string[] }) => void | - | Disparado ao adicionar ou remover uma tag (força o modo interativo). | | onInputValueChange | (details: { inputValue: string }) => void | - | Disparado conforme o campo de texto muda (força o modo interativo). | | interactive | boolean | - | Força ou impede a hidratação como ilha. |

Configuração do CMS

- label: Tags Field
  name: tagsField
  widget: object
  fields:
    - { label: Label, name: label, widget: string, required: false }
    - { label: Helper Text, name: helperText, widget: string, required: false }
    - { label: Error Text, name: errorText, widget: string, required: false }
    - { label: Default Tags, name: defaultValue, widget: list, required: false }

Hidratação

Nível 2: Hidrata quando value, inputValue, defaultValue, defaultInputValue, onValueChange, ou onInputValueChange está presente.