Method createCheckbox

src/api/pdf-form.ts:640–687

* Create a new checkbox field. * * @param name - Field name (must be unique) * @param options - Checkbox options * @returns The created checkbox field * @throws {Error} If a field with the same name already exists * * @example * ```typescript * const agreeCheckbox = form.c

(name: string, options: CheckboxOptions = {})

   * ```
   */
  createCheckbox(name: string, options: CheckboxOptions = {}): CheckboxField {
    this.validateUniqueName(name);

    const onValue = options.onValue ?? "Yes";
    const isChecked = options.defaultChecked ?? false;

    // Button field type without Radio or Pushbutton flags = checkbox
    // Create field dictionary with /Kids array (separate widget model)
    const fieldDict = PdfDict.of({
      FT: PdfName.of("Btn"),
      T: PdfString.fromString(name),
      Kids: new PdfArray([]),
      V: PdfName.of(isChecked ? onValue : "Off"),
    });

    if (isChecked) {
      fieldDict.set("DV", PdfName.of(onValue));
    }

    // Store symbol preference as metadata on field
    if (options.symbol) {
      // Store in custom key for appearance generation
      fieldDict.set("_Symbol", PdfName.of(options.symbol));
    }

    // Store styling metadata
    this.storeFieldStyling(fieldDict, options);

    // Register and add to form
    const fieldRef = this._ctx.registry.register(fieldDict);
    this._acroForm.addField(fieldRef);

    // Create the CheckboxField instance
    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
    const field = createFormField(
      fieldDict,
      fieldRef,
      this._ctx.registry,
      this._acroForm,
      name,
    ) as CheckboxField;

    // Add to cache
    this.allFields.push(field);
    this.fieldsByName.set(name, field);

    return field;
  }

  /**
   * Create a new radio button group.