# Switches Configuration Options in Rime Schema Files: The Complete Wanxiang Guide

> Explore Rime schema switches configuration options with the amzxyz/rime_wanxiang guide. Learn to control input modes for ASCII, emoji, and character sets.

- Repository: [amzxyz/rime_wanxiang](https://github.com/amzxyz/rime_wanxiang)
- Tags: deep-dive
- Published: 2026-02-24

---

**Rime schema switches are UI-level toggles defined under the top-level `switches:` key that enable real-time input mode changes, using fields like `name`, `options`, `states`, and `reset` to configure binary or multi-state behaviors such as ASCII mode, emoji filtering, and character set conversion.**

The `amzxyz/rime_wanxiang` repository provides production-ready examples of switches configuration options in Rime schema files, demonstrating how YAML declarations control input method behaviors ranging from language modes to tone display. These configurations determine how users interact with toggles via the status bar and key bindings, while also serving as runtime flags for Lua processors. Understanding the switch syntax is essential for customizing any Rime-based input method.

## Core Switch Fields and Syntax

A switch is a map entry under the `switches:` list that may contain the following fields:

- **`name`** – String identifier used by the engine and key-binding rules (e.g., `ascii_mode`, `emoji`, `charset_filter`).
- **`options`** – Array of mutually-exclusive option identifiers for multi-state switches (e.g., `[raw_input, tone_display, full_pinyin]`).
- **`states`** – Array of human-readable UI labels displayed in the status bar; index order matches internal state values (e.g., `[中文, 英文]`).
- **`reset`** *(optional)* – Integer index specifying the default state when the schema loads or window focus changes (e.g., `0` for first state, `2` for third).
- **`abbrev`** *(optional)* – Single-character shortcut displayed when the schema appears in a selector menu.

Switches operate in two modes. A **`name`** field creates a binary toggle between two states (off/on). An **`options`** field creates an enumerated switch cycling through three or more mutually exclusive choices, where the first option serves as the default unless `reset` overrides it.

## Switches Configuration Examples in Wanxiang

The Wanxiang project implements diverse switch patterns across its schema variants, from feature-rich pinyin configurations to minimal single-toggle setups.

### Full Pinyin Schema Implementation

In [`wanxiang/wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang/wanxiang.schema.yaml) (lines 21–40), the primary schema defines ten distinct switches controlling ASCII mode, punctuation, full-width characters, emoji filtering, translation modes, tone display, simplification conversion, comments, super tips, and character set priority:

```yaml
switches:
  - name: ascii_mode                    # 中英输入状态

    states: [ 中文, 英文 ]
  - name: ascii_punct                   # 中英标点

    states: [ 中标, 英标 ]
  - name: full_shape                    # 全角/半角

    states: [ 半角, 全角 ]
  - name: emoji                         # Emoji 过滤

    states: [表情关, 表情开]
  - name: chinese_english               # 翻译模式

    states: [ 翻译关, 翻译开 ]
  - options: [ raw_input, tone_display, full_pinyin ]
    states: [ 原编码, 有声调, 无声调 ]
    reset: 2
  - options: [ s2s, s2t, s2hk, s2tw ]   # 简繁转换

    states: [ 简体, 通繁, 港繁, 臺繁 ]
  - options: [comment_off, tone_hint, toneless_hint]
    states: [ 注释关, 有声调, 无声调 ]
    reset: 2
  - name: super_tips
    states: [ 提示关, 提示开 ]
    reset: 1
  - name: charset_filter
    states: [ 大字集, 小字集 ]
    reset: 0
  - name: char_priority
    states: [词组先, 单字先]

```

Notice the multi-option blocks using `options` rather than `name`, particularly for tone display (`reset: 2` forces "无声调" as the default) and simplification chains.

### Nine-Key Variant Adjustments

The T9 schema in [`wanxiang/wanxiang_t9.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang/wanxiang_t9.schema.yaml) (lines 20–46) replicates the core switches while adding abbreviation controls specific to nine-key input:

```yaml
switches:
  - name: ascii_mode
    states: [ 中文, 英文 ]
  - name: ascii_punct
    states: [ 中标, 英标 ]
  - name: full_shape
    states: [ 半角, 全角 ]
  - name: emoji
    states: [表情关, 表情开]
  - name: chinese_english
    states: [ 翻译关, 翻译开 ]
  - name: charset_filter
    states: [ 大字集, 小字集 ]
    reset: 0
  - options: [ raw_input, tone_display, full_pinyin ]
    states: [ 原编码, 有声调, 无声调 ]
    reset: 2
  - options: [ s2s, s2t, s2hk, s2tw ]
    states: [ 简体, 通繁, 港繁, 臺繁 ]
  - options: [comment_off, tone_hint, toneless_hint]
    states: [ 注释关, 有声调, 无声调 ]
    reset: 2
  - name: super_tips
    states: [ 提示关, 提示开 ]
    reset: 1
  - options: [abbrev_off, abbrev_lazy, abbrev_always]
    states: [简码关, 空出简, 总出简]
    reset: 2

```

The `abbrev_*` options demonstrate how multi-state switches control whether short-code candidates are suppressed, shown lazily, or always displayed.

### Minimal English Configuration

For contrast, [`wanxiang/wanxiang_english.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang/wanxiang_english.schema.yaml) (lines 11–15) shows a minimal single-switch setup:

```yaml
switches:
  - name: ascii_mode
    reset: 0
    states: [整句, 字母]

```

Here `reset: 0` ensures the schema initializes in "整句" (sentence) mode whenever the user activates it.

## Runtime Integration with Key Bindings and Lua

Switches are manipulated at runtime through key bindings defined in `key_binder` presets or custom Lua processors. The engine exposes switch states via `ctx:get_option("switch_name")` and updates them via `ctx:set_option("switch_name", boolean)`.

The following Lua filter illustrates how to read and toggle the `emoji` switch programmatically:

```lua
-- super_tips.lua (simplified illustration)
local function init(env)
  -- Initialize the emoji option if needed
  env.engine:set_option("emoji", false)
end

local function filter(input, env)
  local ctx = env.engine.context
  -- Example: Toggle emoji filter when 'e' is pressed in ASCII mode
  if ctx.keycode == 101 and ctx:get_option("ascii_mode") then
    local current = ctx:get_option("emoji")
    ctx:set_option("emoji", not current)
    return 2  -- Keep current input unchanged
  end
  return 1
end

```

The `states` arrays defined in the YAML determine the labels appearing in the candidate list or status bar when switches change. When `reset` values are specified, the engine automatically applies those defaults during schema reloads or window focus events.

## Summary

- **Binary toggles** use the `name` field with two `states`, while **multi-option switches** use the `options` array with three or more choices.
- The **`reset`** field controls which state index (0-based) becomes active when a schema loads or regains focus.
- Switch identifiers are referenced by **`key_binder`** configurations for hotkeys and by **Lua filters** via `ctx:get_option()` and `ctx:set_option()`.
- The [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.schema.yaml), [`wanxiang_t9.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang_t9.schema.yaml), and [`wanxiang_english.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang_english.schema.yaml) files demonstrate progressive complexity from ten-switch configurations down to single-toggle minimal setups.
- **`states`** provide localized UI feedback, while **`abbrev`** offers quick selection shortcuts in schema menus.

## Frequently Asked Questions

### What is the difference between `name` and `options` in a Rime switch?

The **`name`** field creates a binary toggle between exactly two states (typically off/on), such as `ascii_mode` switching between Chinese and English input. The **`options`** field defines an array of three or more mutually exclusive identifiers, creating a cycle-through switch like the tone display modes (`raw_input`, `tone_display`, `full_pinyin`). When using `options`, the first entry is the default unless overridden by a `reset` value.

### How does the `reset` field affect switch behavior?

The **`reset`** field accepts an integer index (starting at 0) that specifies which state becomes active when the schema is first loaded, reselected, or when the input window regains focus. For example, `reset: 2` in the `full_pinyin` options block forces the switch to start at the third state ("无声调") rather than the default first state ("原编码").

### Can switches control custom Lua filters?

Yes. Lua processors and filters access switch states through the engine context using `ctx:get_option("switch_name")` to read values and `ctx:set_option("switch_name", value)` to modify them. This allows custom scripts to conditionally alter candidate generation, pre-edit formatting, or translation behavior based on user toggles defined in the schema's `switches` section.

### How do I add a new toggle to my Rime schema?

Add a new list item under the `switches:` key in your [`.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/.schema.yaml) file. For a binary toggle, provide a unique `name` and two `states` labels. For multiple choices, use `options` with an array of identifiers and matching `states` labels. Optionally include `reset` to set a non-default initial state or `abbrev` for a single-character menu shortcut. After editing, redeploy Rime to load the new switch configuration.