Kappa / Checkbox

Verify mesh quality before solving Pre-solver checks are enabled for this case.

<script setup>
import { ref } from "vue";
import { Checkbox } from "@dicehub/kappa/components/checkbox";

const verifyMesh = ref(true);
</script>

<template>
  <Checkbox.Root v-model:checked="verifyMesh" name="verify-mesh">
    <Checkbox.Control />
    <Checkbox.Label>Verify mesh quality before solving</Checkbox.Label>
  </Checkbox.Root>
</template>

Installation

Barrel

import {
  Checkbox,
  CheckboxRoot,
  CheckboxRootProvider,
  CheckboxGroup,
  CheckboxControl,
  CheckboxIndicator,
  CheckboxLabel,
  CheckboxContext,
} from "@dicehub/kappa";

Granular

import {
  Checkbox,
  CheckboxRoot,
  CheckboxRootProvider,
  CheckboxGroup,
  CheckboxControl,
  CheckboxIndicator,
  CheckboxLabel,
  CheckboxContext,
} from "@dicehub/kappa/components/checkbox";

Usage

Every checkbox needs a Control and a Label. The root renders a native hidden input automatically, so name, value,form, and required participate in form submission without extra markup.

Export residuals after each write interval

<script setup>
import { Checkbox } from "@dicehub/kappa/components/checkbox";
</script>

<template>
  <Checkbox.Root default-checked name="residual-export" value="residuals">
    <Checkbox.Control />
    <Checkbox.Label>Export residuals after each write interval</Checkbox.Label>
  </Checkbox.Root>
</template>

Composition

Typical part hierarchy

Checkbox.Group (optional)
└── Checkbox.Root
    ├── Checkbox.Control
    │   └── Checkbox.Indicator
    └── Checkbox.Label

Ark UI owns the checkbox machine, tri-state logic, label activation, focus visibility, and the hidden input. Kappa owns the compound API, the default check and indeterminate marks, dense control geometry, states, and semantic tokens.

Root owns the checked state and renders the hidden input for forms.
Control is the visual box. Its slot replaces the default marks when custom content is given.
Indicator wraps one state mark. Set indeterminate to show it only in the indeterminate state.
Label names the checkbox and toggles it on click.
Group shares name, state, and a selection limit across related checkboxes.

See the Ark UI Checkboxguide for the primitive behavior contract. Use RootProvider withuseCheckbox when an external machine must own the state.

<script setup>
import {
  CheckboxRoot,
  CheckboxControl,
  CheckboxIndicator,
  CheckboxLabel,
} from "@dicehub/kappa/components/checkbox";
</script>

<template>
  <CheckboxRoot>
    <CheckboxControl>
      <CheckboxIndicator>
        <CustomCheckIcon />
      </CheckboxIndicator>
      <CheckboxIndicator indeterminate>
        <CustomMinusIcon />
      </CheckboxIndicator>
    </CheckboxControl>
    <CheckboxLabel>Custom indicator marks</CheckboxLabel>
  </CheckboxRoot>
</template>

Examples

Basic

An uncontrolled checkbox starts unchecked and manages its own state.

Enable adaptive time step

<script setup>
import { Checkbox } from "@dicehub/kappa/components/checkbox";
</script>

<template>
  <Checkbox.Root>
    <Checkbox.Control />
    <Checkbox.Label>Enable adaptive time step</Checkbox.Label>
  </Checkbox.Root>
</template>

Indeterminate

A parent checkbox summarizes a partial selection with"indeterminate". Clicking it selects or clears every item.

Monitor all fields

ResidualsForce coefficientsPressure spectra

<script setup>
import { computed, ref } from "vue";
import { Checkbox } from "@dicehub/kappa/components/checkbox";

const fieldOptions = [
  { value: "residuals", label: "Residuals" },
  { value: "forces", label: "Force coefficients" },
  { value: "spectra", label: "Pressure spectra" },
];

const selectedFields = ref(["residuals", "forces"]);
const allFieldsState = computed(() => {
  if (selectedFields.value.length === 0) return false;
  return selectedFields.value.length === fieldOptions.length ? true : "indeterminate";
});
const toggleAllFields = () => {
  selectedFields.value =
    selectedFields.value.length === fieldOptions.length
      ? []
      : fieldOptions.map((option) => option.value);
};
</script>

<template>
  <Checkbox.Root :checked="allFieldsState" @checked-change="toggleAllFields">
    <Checkbox.Control />
    <Checkbox.Label>Monitor all fields</Checkbox.Label>
  </Checkbox.Root>
  <Checkbox.Group v-model="selectedFields" name="monitored-fields">
    <Checkbox.Root v-for="option in fieldOptions" :key="option.value" :value="option.value">
      <Checkbox.Control />
      <Checkbox.Label>{{ option.label }}</Checkbox.Label>
    </Checkbox.Root>
  </Checkbox.Group>
</template>

Group

Checkbox.Group binds item values into one array withv-model. At maxSelectedValues, unchecked items become disabled until a selection is removed. Name the group witharia-labelledby or aria-label.

Export formats

VTK surface dataCSV force historyHDF5 field archive

Selected: vtk (max 2)

<script setup>
import { ref } from "vue";
import { Checkbox } from "@dicehub/kappa/components/checkbox";

const exportSelection = ref(["vtk"]);
</script>

<template>
  <span id="export-group-label">Export formats</span>
  <Checkbox.Group
    v-model="exportSelection"
    aria-labelledby="export-group-label"
    name="export-formats"
    :max-selected-values="2"
  >
    <Checkbox.Root value="vtk">
      <Checkbox.Control />
      <Checkbox.Label>VTK surface data</Checkbox.Label>
    </Checkbox.Root>
    <Checkbox.Root value="csv">
      <Checkbox.Control />
      <Checkbox.Label>CSV force history</Checkbox.Label>
    </Checkbox.Root>
    <Checkbox.Root value="hdf5">
      <Checkbox.Control />
      <Checkbox.Label>HDF5 field archive</Checkbox.Label>
    </Checkbox.Root>
  </Checkbox.Group>
</template>

Bordered Items

The root renders a label, so a bordered row can carry a title and a description and still toggle from any point. This is a composition pattern, not a variant: put the layout class on Root and mark the checked row with:has([data-state="checked"]).

Run pre-solver mesh checksBlocks the run while quality metrics fail.Write residual historyAppends normalized residuals at every iteration.

<script setup>
import { ref } from "vue";
import { Checkbox } from "@dicehub/kappa/components/checkbox";

const meshChecks = ref(true);
const residualHistory = ref(false);
</script>

<template>
  <Checkbox.Root v-model:checked="meshChecks" class="settings-row" name="mesh-checks">
    <Checkbox.Control />
    <Checkbox.Label class="settings-row__text">
      <span class="settings-row__title">Run pre-solver mesh checks</span>
      <span class="settings-row__description">Blocks the run while quality metrics fail.</span>
    </Checkbox.Label>
  </Checkbox.Root>
  <Checkbox.Root v-model:checked="residualHistory" class="settings-row" name="residual-history">
    <Checkbox.Control />
    <Checkbox.Label class="settings-row__text">
      <span class="settings-row__title">Write residual history</span>
      <span class="settings-row__description">Appends normalized residuals at every iteration.</span>
    </Checkbox.Label>
  </Checkbox.Root>
</template>

<style scoped>
/* The root renders a label, so the whole bordered row toggles the checkbox. */
.settings-row {
  width: 100%;
  align-items: flex-start;
  gap: 0.625rem;
  border: 1px solid var(--kappa-line, #e3e6eb);
  border-radius: 0.5rem;
  padding: 0.625rem 0.75rem;
}

.settings-row:has([data-state="checked"]) {
  border-color: var(--kappa-accent, #4356e8);
}

.settings-row__text {
  display: grid;
  gap: 0.125rem;
}

.settings-row__description {
  color: var(--kappa-subtle, #6c7480);
  font-size: 0.75rem;
}
</style>

Controlled

Use v-model:checked for live state. The state union istrue, false, or "indeterminate".

Run orthogonal quality check State: true

<script setup>
import { ref } from "vue";
import { Checkbox } from "@dicehub/kappa/components/checkbox";

const meshChecked = ref(true);
</script>

<template>
  <Checkbox.Root :checked="meshChecked" @update:checked="meshChecked = $event">
    <Checkbox.Control />
    <Checkbox.Label>Run orthogonal quality check</Checkbox.Label>
  </Checkbox.Root>
  <p>State: {{ meshChecked }}</p>
</template>

States

Disabled blocks focus and changes. Read-only keeps focus but blocks changes. Invalid marks the control and needs a clear text description.

Disabled while meshingRead-only license option

Accept the compute policy

Acceptance is required to submit the job.

<script setup>
import { Checkbox } from "@dicehub/kappa/components/checkbox";
</script>

<template>
  <Checkbox.Root disabled>
    <Checkbox.Control />
    <Checkbox.Label>Disabled while meshing</Checkbox.Label>
  </Checkbox.Root>
  <Checkbox.Root read-only default-checked>
    <Checkbox.Control />
    <Checkbox.Label>Read-only license option</Checkbox.Label>
  </Checkbox.Root>
  <Checkbox.Root invalid aria-describedby="terms-error">
    <Checkbox.Control />
    <Checkbox.Label>Accept the compute policy</Checkbox.Label>
  </Checkbox.Root>
  <p id="terms-error">Acceptance is required to submit the job.</p>
</template>

Accessibility

The hidden input keeps native checkbox semantics, keyboard focus, and form behavior.
Space toggles the focused checkbox; the label text toggles it on click.
The indeterminate state sets the native input's mixed state, so assistive technology announces it correctly.
Every checkbox needs a Label. Connect help or error text with aria-describedby.
Name groups with aria-labelledby or aria-label on Checkbox.Group.
Keyboard focus stays visible through an outline on the control.
Use name and form for native form association.

API Reference

Checkbox.Root

Prop	Type	Default	Description
`checked`	`CheckboxCheckedState`	`-`	Controlled checked state; supports v-model:checked.
`defaultChecked`	`CheckboxCheckedState`	`false`	Initial state for uncontrolled use; accepts true, false, or "indeterminate".
`disabled`	`boolean`	`false`	Blocks interaction and form submission.
`readOnly`	`boolean`	`false`	Keeps focus and selection but blocks changes.
`required`	`boolean`	`false`	Marks the input required for native form validation.
`invalid`	`boolean`	`false`	Applies the invalid data attribute and danger styling.
`name`	`string`	`-`	Form field name submitted by the hidden input.
`value`	`string`	`"on"`	Submitted value, and the item key inside Checkbox.Group.
`form`	`string`	`-`	Associates the hidden input with an external form id.
`id`	`string`	`generated`	Stable identifier for the checkbox state machine.
`ids`	`CheckboxRootProps['ids']`	`generated`	Overrides generated root, control, label, and hidden input IDs.
`asChild`	`boolean`	`false`	Merges root behavior into the single child element.

Checkbox.Group

Prop	Type	Default	Description
`modelValue`	`string[]`	`-`	Controlled list of checked item values; supports v-model.
`defaultValue`	`string[]`	`[]`	Initially checked item values for uncontrolled use.
`name`	`string`	`-`	Shared form field name for every item in the group.
`disabled`	`boolean`	`false`	Disables every checkbox in the group.
`readOnly`	`boolean`	`false`	Blocks changes on every checkbox in the group.
`invalid`	`boolean`	`false`	Marks every checkbox in the group invalid.
`maxSelectedValues`	`number`	`-`	Disables unchecked items once this many values are checked.
`asChild`	`boolean`	`false`	Merges group behavior into the single child element.

Parts

Part	Element	Description
`Checkbox.Control`	`span`	Visual box; renders the default check and indeterminate marks unless its slot is overridden.
`Checkbox.Indicator`	`div`	State mark wrapper; shown when checked, or when indeterminate with its indeterminate prop.
`Checkbox.Label`	`span`	Accessible label text; clicking it toggles the checkbox.
`Checkbox.Context`	`renderless`	Exposes the root checkbox API to its slot.
`Checkbox.RootProvider`	`label`	Root variant driven by an external useCheckbox machine.

Events

Event	Payload	Description
`update:checked`	`CheckboxCheckedState`	Emitted on every state change; drives v-model:checked.
`checkedChange`	`{ checked: CheckboxCheckedState }`	Ark UI detail emitted after the state changes.
`update:modelValue`	`string[]`	Group event that drives v-model on Checkbox.Group.
`valueChange`	`string[]`	Group event emitted after an item checks or unchecks.

Exports

Export	Description
`Checkbox`	Compound API exposing Root, RootProvider, Group, Control, Indicator, Label, and Context.
`CheckboxRoot`	Unaugmented root component with automatic hidden input.
`CheckboxRootProvider`	Root driven by an external useCheckbox machine.
`CheckboxGroup`	Shared name, state, and max-selection boundary for related checkboxes.
`CheckboxControl`	Visual control with default state marks.
`CheckboxIndicator`	Customizable state mark.
`CheckboxLabel`	Accessible checkbox label.
`CheckboxContext`	Renderless context consumer.
`CheckboxProps`	Public root props and Ark UI state contract.
`CheckboxEmits`	Root event contract.
`CheckboxGroupProps`	Public group props.
`CheckboxGroupEmits`	Group event contract.
`CheckboxCheckedState`	boolean \| "indeterminate" state union.
`CheckboxCheckedChangeDetails`	Payload for checkedChange.
`useCheckbox`	Ark UI machine hook for external state control.
`useCheckboxGroup`	Ark UI group machine hook.
`checkboxAnatomy`	Ark UI part anatomy metadata.