Checkbox

CheckboxGitLab
Um elemento de input para alternar entre os estados marcado e desmarcado.

Uso

Use a diretiva v-model para controlar o estado marcado do Checkbox.

<script setup lang="ts">
const value = ref(true)
</script>

<template>
  <NCheckbox v-model="value" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(true)
</script>

<template>
  <NCheckbox v-model="value" />
</template>

Use a prop default-value para definir o valor inicial quando você não precisa controlar o estado.

<template>
  <NCheckbox default-value />
</template>

Indeterminado

Use o valor indeterminate na diretiva v-model ou na prop default-value para colocar o Checkbox em um estado indeterminado.

<template>
  <NCheckbox default-value="indeterminate" />
</template>

Ícone de indeterminado

Use a prop indeterminate-icon para personalizar o ícone de indeterminado. O padrão é i-lucide-minus.

<template>
  <NCheckbox default-value="indeterminate" indeterminate-icon="i-lucide-plus" />
</template>
Você pode personalizar esse ícone globalmente no seu app.config.ts na chave ui.icons.minus.
Você pode personalizar esse ícone globalmente no seu vite.config.ts na chave ui.icons.minus.

Label

Use a prop label para definir o rótulo do Checkbox.

<template>
  <NCheckbox label="Check me" />
</template>

Ao usar a prop required, um asterisco é adicionado ao lado do rótulo.

<template>
  <NCheckbox required label="Check me" />
</template>

Descrição

Use a prop description para definir a descrição do Checkbox.

This is a checkbox.

<template>
  <NCheckbox label="Check me" description="This is a checkbox." />
</template>

Ícone

Use a prop icon para definir o ícone do Checkbox quando ele está marcado. O padrão é i-lucide-check.

<template>
  <NCheckbox icon="i-lucide-heart" default-value label="Check me" />
</template>
Você pode personalizar esse ícone globalmente no seu app.config.ts na chave ui.icons.check.
Você pode personalizar esse ícone globalmente no seu vite.config.ts na chave ui.icons.check.

Cor

Use a prop color para alterar a cor do Checkbox.

<template>
  <NCheckbox color="neutral" default-value label="Check me" />
</template>

Variante

Use a prop variant para alterar a variante do Checkbox.

<template>
  <NCheckbox color="primary" variant="card" default-value label="Check me" />
</template>

Tamanho

Use a prop size para alterar o tamanho do Checkbox.

<template>
  <NCheckbox size="xl" variant="list" default-value label="Check me" />
</template>

Indicador

Use a prop indicator para alterar a posição ou ocultar o indicador. O padrão é start.

<template>
  <NCheckbox indicator="end" variant="card" default-value label="Check me" />
</template>

Desabilitado

Use a prop disabled para desabilitar o Checkbox.

<template>
  <NCheckbox disabled label="Check me" />
</template>

API

Props

Prop Default Type
as'div'any

The element or component this component should render as.

label string
description string
color'primary' "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral"
variant'list' "card" | "list"
size'md' "xs" | "sm" | "md" | "lg" | "xl"
indicator'start' "start" | "end" | "hidden"

Position of the indicator.

highlightboolean

Highlight the ring color like a focus state.

iconappConfig.ui.icons.checkany

The icon displayed when checked.

indeterminateIconappConfig.ui.icons.minusany

The icon displayed when the checkbox is indeterminate.

disabledboolean

When true, prevents the user from interacting with the checkbox

requiredboolean

When true, indicates that the user must set the value before the owning form can be submitted.

name string

The name of the field. Submitted with its owning form as part of a name/value pair.

value"on" null | string | number | bigint | Record<string, any>

The value given as data when submitted with a name.

id string

Id of the element

defaultValue T | "indeterminate"

The value of the checkbox when it is initially rendered. Use when you do not need to control its value.

modelValue null | T | "indeterminate"

The controlled value of the checkbox. Can be binded with v-model.

trueValue T

The value used when the checkbox is checked. Defaults to true.

falseValue T

The value used when the checkbox is unchecked. Defaults to false.

autofocus false | true | "true" | "false"
ui { root?: SlotClass; container?: SlotClass; base?: SlotClass; indicator?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; }
Este componente também suporta todos os atributos HTML nativos de <button>.

Slots

Slot Type
label{ label: string | undefined; }
description{ description: string | undefined; }

Emits

Event Type
change[event: Event]
update:modelValue[value: T | "indeterminate"]

Tema

app.config.ts
export default defineAppConfig({
  ui: {
    checkbox: {
      slots: {
        root: 'relative flex items-start',
        container: 'flex items-center',
        base: 'rounded-sm ring ring-inset ring-accented overflow-hidden focus-visible:outline-3',
        indicator: 'flex items-center justify-center size-full text-inverted',
        icon: 'shrink-0 size-full',
        wrapper: 'w-full',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            base: 'outline-primary/25 focus-visible:ring-primary',
            indicator: 'bg-primary'
          },
          secondary: {
            base: 'outline-secondary/25 focus-visible:ring-secondary',
            indicator: 'bg-secondary'
          },
          accent: {
            base: 'outline-accent/25 focus-visible:ring-accent',
            indicator: 'bg-accent'
          },
          success: {
            base: 'outline-success/25 focus-visible:ring-success',
            indicator: 'bg-success'
          },
          info: {
            base: 'outline-info/25 focus-visible:ring-info',
            indicator: 'bg-info'
          },
          warning: {
            base: 'outline-warning/25 focus-visible:ring-warning',
            indicator: 'bg-warning'
          },
          error: {
            base: 'outline-error/25 focus-visible:ring-error',
            indicator: 'bg-error'
          },
          neutral: {
            base: 'outline-inverted/25 focus-visible:ring-inverted',
            indicator: 'bg-inverted'
          }
        },
        variant: {
          list: {
            root: ''
          },
          card: {
            root: 'border border-muted rounded-lg'
          }
        },
        indicator: {
          start: {
            root: 'flex-row',
            wrapper: 'ms-2'
          },
          end: {
            root: 'flex-row-reverse',
            wrapper: 'me-2'
          },
          hidden: {
            base: 'sr-only',
            wrapper: 'text-center'
          }
        },
        size: {
          xs: {
            base: 'size-3',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          sm: {
            base: 'size-3.5',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          md: {
            base: 'size-4',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          lg: {
            base: 'size-4.5',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          xl: {
            base: 'size-5',
            container: 'h-6',
            wrapper: 'text-base'
          }
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        disabled: {
          true: {
            root: 'opacity-75',
            base: 'cursor-not-allowed',
            label: 'cursor-not-allowed',
            description: 'cursor-not-allowed'
          }
        },
        highlight: {
          true: ''
        },
        checked: {
          true: ''
        }
      },
      compoundVariants: [
        {
          size: 'xs',
          variant: 'card',
          class: {
            root: 'p-2.5'
          }
        },
        {
          size: 'sm',
          variant: 'card',
          class: {
            root: 'p-3'
          }
        },
        {
          size: 'md',
          variant: 'card',
          class: {
            root: 'p-3.5'
          }
        },
        {
          size: 'lg',
          variant: 'card',
          class: {
            root: 'p-4'
          }
        },
        {
          size: 'xl',
          variant: 'card',
          class: {
            root: 'p-4.5'
          }
        },
        {
          color: 'primary',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-primary'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-inverted'
          }
        },
        {
          variant: 'card',
          disabled: true,
          class: {
            root: 'cursor-not-allowed'
          }
        },
        {
          color: 'primary',
          highlight: true,
          class: {
            base: 'ring-primary'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            base: 'ring-inverted'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary',
        variant: 'list',
        indicator: 'start'
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        checkbox: {
          slots: {
            root: 'relative flex items-start',
            container: 'flex items-center',
            base: 'rounded-sm ring ring-inset ring-accented overflow-hidden focus-visible:outline-3',
            indicator: 'flex items-center justify-center size-full text-inverted',
            icon: 'shrink-0 size-full',
            wrapper: 'w-full',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                base: 'outline-primary/25 focus-visible:ring-primary',
                indicator: 'bg-primary'
              },
              secondary: {
                base: 'outline-secondary/25 focus-visible:ring-secondary',
                indicator: 'bg-secondary'
              },
              accent: {
                base: 'outline-accent/25 focus-visible:ring-accent',
                indicator: 'bg-accent'
              },
              success: {
                base: 'outline-success/25 focus-visible:ring-success',
                indicator: 'bg-success'
              },
              info: {
                base: 'outline-info/25 focus-visible:ring-info',
                indicator: 'bg-info'
              },
              warning: {
                base: 'outline-warning/25 focus-visible:ring-warning',
                indicator: 'bg-warning'
              },
              error: {
                base: 'outline-error/25 focus-visible:ring-error',
                indicator: 'bg-error'
              },
              neutral: {
                base: 'outline-inverted/25 focus-visible:ring-inverted',
                indicator: 'bg-inverted'
              }
            },
            variant: {
              list: {
                root: ''
              },
              card: {
                root: 'border border-muted rounded-lg'
              }
            },
            indicator: {
              start: {
                root: 'flex-row',
                wrapper: 'ms-2'
              },
              end: {
                root: 'flex-row-reverse',
                wrapper: 'me-2'
              },
              hidden: {
                base: 'sr-only',
                wrapper: 'text-center'
              }
            },
            size: {
              xs: {
                base: 'size-3',
                container: 'h-4',
                wrapper: 'text-xs'
              },
              sm: {
                base: 'size-3.5',
                container: 'h-4',
                wrapper: 'text-xs'
              },
              md: {
                base: 'size-4',
                container: 'h-5',
                wrapper: 'text-sm'
              },
              lg: {
                base: 'size-4.5',
                container: 'h-5',
                wrapper: 'text-sm'
              },
              xl: {
                base: 'size-5',
                container: 'h-6',
                wrapper: 'text-base'
              }
            },
            required: {
              true: {
                label: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            },
            disabled: {
              true: {
                root: 'opacity-75',
                base: 'cursor-not-allowed',
                label: 'cursor-not-allowed',
                description: 'cursor-not-allowed'
              }
            },
            highlight: {
              true: ''
            },
            checked: {
              true: ''
            }
          },
          compoundVariants: [
            {
              size: 'xs',
              variant: 'card',
              class: {
                root: 'p-2.5'
              }
            },
            {
              size: 'sm',
              variant: 'card',
              class: {
                root: 'p-3'
              }
            },
            {
              size: 'md',
              variant: 'card',
              class: {
                root: 'p-3.5'
              }
            },
            {
              size: 'lg',
              variant: 'card',
              class: {
                root: 'p-4'
              }
            },
            {
              size: 'xl',
              variant: 'card',
              class: {
                root: 'p-4.5'
              }
            },
            {
              color: 'primary',
              variant: 'card',
              class: {
                root: 'has-data-[state=checked]:border-primary'
              }
            },
            {
              color: 'neutral',
              variant: 'card',
              class: {
                root: 'has-data-[state=checked]:border-inverted'
              }
            },
            {
              variant: 'card',
              disabled: true,
              class: {
                root: 'cursor-not-allowed'
              }
            },
            {
              color: 'primary',
              highlight: true,
              class: {
                base: 'ring-primary'
              }
            },
            {
              color: 'neutral',
              highlight: true,
              class: {
                base: 'ring-inverted'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            color: 'primary',
            variant: 'list',
            indicator: 'start'
          }
        }
      }
    })
  ]
})
Some colors in compoundVariants are omitted for readability. Check out the source code on GitLab.

Changelog

No recent changes

Skeleton

Um placeholder para exibir enquanto o conteúdo está carregando.

CheckboxGroup

Um conjunto de botões de checklist para selecionar várias opções em uma lista.