Introduction

fs-form-checkbox is a form-item multi-select control used to choose multiple items from a set of options. It is built on ava-ui/fxui/fs-checkbox-group and ava-ui/fxui/fs-checkbox, uses a capsule style, and arranges items horizontally. It can be used standalone or together with fs-form.

Usage

When importing locally, configure it in the page's index.json:

"usingComponents": {
  "fs-form-checkbox": "/avaui-sub/fs-form/fs-form-checkbox/index"
}

When used together with fs-form:

"usingComponents": {
  "fs-form": "/avaui-sub/fs-form/index",
  "fs-form-item": "/avaui-sub/fs-form/fs-form-item/index",
  "fs-form-checkbox": "/avaui-sub/fs-form/fs-form-checkbox/index"
}

PWC (custom component/plugin) usage: only the usingComponents registration uses the avaComponent:// protocol; other usage is the same.

When used standalone:

"usingComponents": {
  "fs-form-checkbox": "avaComponent://avaui-sub/fs-form/fs-form-checkbox/index"
}

Code Demos

1. Basic Usage

Bind the currently selected value array via value, and configure the option list via options.

2. Disabled State

Disable the entire multi-select group via the disabled attribute, or disable a single option within options.

3. Dropdown Selection Mode

Enable dropdown selection mode via mode="dropdown". The component will display in a style similar to fs-form-date, and a multi-select picker pops up on click. The names of selected options are displayed separated by commas.

4. Used with fs-form

fs-form-checkbox can be used as the content control of an fs-form-item, supporting form validation and data collection.

---

API

fs-form-checkbox Attributes

Parameter	Description	Type	Optional Values	Default
value	Currently selected value array	Array	—	[]
options	Option list	Array	—	[]
disabled	Whether disabled	Boolean	—	false
mode	Display mode	String	inline/dropdown	inline
placeholder	Placeholder text in dropdown mode	String	—	''
pickerTitle	Dropdown picker title	String	—	''
bordered	Whether to show a border, only effective in dropdown mode	Boolean	—	false
showSearch	Whether to show the search box (dropdown mode)	Boolean	—	false
checkboxType	Option style type; only card takes effect in dropdown mode	String	capsule/card	capsule
direction	Option arrangement direction in inline mode	String	row/column	row

options Array Item

Field	Description	Type
label	Option display text	String
value	Option value	any
disabled	Whether this option is disabled	Boolean

fs-form-checkbox Events

Event Name	Description	Callback Parameters
change	When the selected value changes

Note: The change event has bubbles: true and composed: true enabled, so it can be captured by fs-form-item for form validation.

---

Validation Rules

Checkbox validation requires specifying type: 'array', and can be combined with min / max to limit the number of selections:

{
  hobbies: [
    { 
      required: true, 
      message: 'Please select at least one item',
      type: 'array',
      min: 1
    },
    {
      message: 'Select up to 3 items',
      type: 'array',
      max: 3
    }
  ]
}

---

Design Notes

Inline Mode

• Uses a capsule style arranged horizontally; switch to a card style via checkboxType="card"
• Control the arrangement direction via the direction attribute: row (horizontal) / column (vertical)
• Supports disabling a single option and disabling the whole group
• Automatically syncs the selected state to keep the UI consistent with the data

Dropdown Mode

• Styled after fs-form-date, displaying the names of selected options separated by commas
• Built on fs-radio-picker-m for popup multi-select
• Supports the bordered border style, suitable for scenarios requiring a 32px-height input visual
• Supports search, select-all, checkboxType="card" card style, and more
• Suitable for scenarios with many options or where page space needs to be saved

---

打开预览