Command and keyboard-first

Character grid selection

<forma-character-grid-selection>

Per-row selection fields in positioned repeated rows (a 5250-style option column): native text inputs named by their column and row headers and described by the option legend; the application owns what each option does.

Authoring tag
<forma-character-grid-selection>
Behavior owner
Application / Limen
Canonical source
patterns/character-grid-selection.html

Purpose

Character grid selection is the "Work with" idiom: a list of records in a positioned table where each row has a short option field, a legend such as 2=Change 4=Close 5=Display explains the codes, and pressing Enter processes every row whose option changed. Each option field is a native text input in a table cell, named by its column header and its row header through aria-labelledby ("Opt 00417-2231-09") and described by the legend. Forma presents the column, the fields and their states. The application decides which options are valid, reads the changed rows on Enter, and marks rejected rows invalid.

Use when

  • Users act on several records of a list in one pass by typing an option code next to each.
  • A host "Work with" screen is being re-platformed and the option column must stay.
  • Keyboard-only operators need to move row by row with Tab and type codes without leaving the keyboard.

Avoid when

Behavior to know

  • Fields keep native semantics inside native table semantics; row headers identify each record.
  • Each field is exactly data-forma-len cells wide; its column may be wider ("Opt" is three cells for a one-cell field).
  • Tab moves down the option column in row-major order; disabled rows are skipped natively.
  • The same required, invalid, disabled and focus cues as other grid fields.

Basic example

The smallest correct markup: the canonical pattern from patterns/character-grid-selection.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal character grid selection

Rendered from the canonical pattern file.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

WORK WITH ACCOUNTS

Type options, press Enter.

2=Change 4=Close 5=Display

Accounts, with a selection option per row
OptAccountNameTypeBalance
00417-2231-09RIVERA, ALEXCHECKING12,480.55
00417-5518-02RIVERA, ALEXSAVINGS8,215.00
00902-1177-40OKAFOR, CHIDILOAN-4,100.00
01233-0040-11NAKAMURA, YUKICHECKING310.72
01233-0040-12NAKAMURA, YUKICLOSED0.00

Bottom

CHECK Option 9 is not valid for 00902-1177-40. Type 2, 4, or 5.

HTML · Minimal character grid selection Raw HTML for HTML · Minimal character grid selection
<forma-character-grid-selection class="forma-component-tag">
<div class="forma-character-grid" data-forma-rows="14" data-forma-columns="80" data-forma-narrow="contained">
  <div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-selection-title" tabindex="0">
    <form class="forma-character-grid__surface">
      <h2 class="forma-character-grid__text" id="character-grid-selection-title" data-forma-row="1" data-forma-col="31" data-forma-len="18" data-forma-emphasis="intensified">WORK WITH ACCOUNTS</h2>
      <p class="forma-character-grid__text" data-forma-row="3" data-forma-col="2" data-forma-len="26">Type options, press Enter.</p>
      <p class="forma-character-grid__text" id="character-grid-selection-legend" data-forma-row="4" data-forma-col="4" data-forma-len="28">2=Change  4=Close  5=Display</p>
      <div class="forma-character-grid__table" data-forma-row="6" data-forma-col="2" data-forma-len="77" data-forma-height="6">
        <table data-forma-gutter="2">
          <caption>Accounts, with a selection option per row</caption>
          <thead><tr><th scope="col" id="character-grid-selection-opt" data-forma-len="3">Opt</th><th scope="col" data-forma-len="14">Account</th><th scope="col" data-forma-len="24">Name</th><th scope="col" data-forma-len="10">Type</th><th scope="col" data-forma-len="12" data-forma-align="end">Balance</th></tr></thead>
          <tbody>
          <tr><td><input class="forma-character-grid__field" id="character-grid-selection-opt-1" name="opt-00417-2231-09" type="text" inputmode="numeric" pattern="[245]" maxlength="1" autocomplete="off" aria-labelledby="character-grid-selection-opt character-grid-selection-row-1" aria-describedby="character-grid-selection-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-row-1">00417-2231-09</th><td>RIVERA, ALEX</td><td>CHECKING</td><td data-forma-align="end">12,480.55</td></tr>
          <tr><td><input class="forma-character-grid__field" id="character-grid-selection-opt-2" name="opt-00417-5518-02" type="text" inputmode="numeric" pattern="[245]" maxlength="1" autocomplete="off" value="5" aria-labelledby="character-grid-selection-opt character-grid-selection-row-2" aria-describedby="character-grid-selection-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-row-2">00417-5518-02</th><td>RIVERA, ALEX</td><td>SAVINGS</td><td data-forma-align="end">8,215.00</td></tr>
          <tr><td><input class="forma-character-grid__field" id="character-grid-selection-opt-3" name="opt-00902-1177-40" type="text" inputmode="numeric" pattern="[245]" maxlength="1" autocomplete="off" value="9" aria-invalid="true" aria-labelledby="character-grid-selection-opt character-grid-selection-row-3" aria-describedby="character-grid-selection-legend character-grid-selection-message" data-forma-len="1"></td><th scope="row" id="character-grid-selection-row-3">00902-1177-40</th><td>OKAFOR, CHIDI</td><td>LOAN</td><td data-forma-align="end">-4,100.00</td></tr>
          <tr><td><input class="forma-character-grid__field" id="character-grid-selection-opt-4" name="opt-01233-0040-11" type="text" inputmode="numeric" pattern="[245]" maxlength="1" autocomplete="off" aria-labelledby="character-grid-selection-opt character-grid-selection-row-4" aria-describedby="character-grid-selection-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-row-4">01233-0040-11</th><td>NAKAMURA, YUKI</td><td>CHECKING</td><td data-forma-align="end">310.72</td></tr>
          <tr><td><input class="forma-character-grid__field" id="character-grid-selection-opt-5" name="opt-01233-0040-12" type="text" inputmode="numeric" pattern="[245]" maxlength="1" autocomplete="off" disabled aria-labelledby="character-grid-selection-opt character-grid-selection-row-5" aria-describedby="character-grid-selection-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-row-5">01233-0040-12</th><td>NAKAMURA, YUKI</td><td>CLOSED</td><td data-forma-align="end">0.00</td></tr>
          </tbody>
        </table>
      </div>
      <p class="forma-character-grid__text" data-forma-row="12" data-forma-col="72" data-forma-len="6">Bottom</p>
      <p class="forma-character-grid__message" id="character-grid-selection-message" role="status" data-forma-severity="validation" data-forma-row="13" data-forma-col="2" data-forma-len="78"><span class="forma-character-grid__severity"><span>CHECK</span></span> Option 9 is not valid for 00902-1177-40. Type 2, 4, or 5.</p>
      <div class="forma-character-grid__group" role="group" aria-label="Function keys">
        <button class="forma-character-grid__key" type="submit" name="action" value="enter" data-forma-action="enter" data-forma-row="14" data-forma-col="2" data-forma-len="13"><kbd>Enter</kbd>=Process</button>
        <button class="forma-character-grid__key" type="submit" name="action" value="pf3" formnovalidate data-forma-action="pf3" data-forma-row="14" data-forma-col="17" data-forma-len="8"><kbd>PF3</kbd>=Exit</button>
        <button class="forma-character-grid__key" type="submit" name="action" value="pf5" formnovalidate data-forma-action="pf5" data-forma-row="14" data-forma-col="27" data-forma-len="11"><kbd>PF5</kbd>=Refresh</button>
        <button class="forma-character-grid__key" type="submit" name="action" value="pf12" formnovalidate data-forma-action="pf12" data-forma-row="14" data-forma-col="40" data-forma-len="11"><kbd>PF12</kbd>=Cancel</button>
      </div>
    </form>
  </div>
</div>
</forma-character-grid-selection>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Options typed before Enter

A "Work with jobs" list where the operator has typed options on two rows but not yet pressed Enter. The legend uses a different vocabulary; only the codes and labels change.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

WORK WITH JOBS

Type options, press Enter.

2=Hold 3=Release 4=End

Active jobs, with a selection option per row
OptJobUserStatus
QPADEV0012OKAFORRUNNING
NIGHTLYGLBATCHSYSWAITING
RPTAGINGRIVERAHELD

INFO Press Enter to process the options you typed.

HTML · Options typed before Enter Raw HTML for HTML · Options typed before Enter
<forma-character-grid-selection class="forma-component-tag">
  <div class="forma-character-grid" data-forma-rows="11" data-forma-columns="60" data-forma-narrow="contained">
    <div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-selection-work-with-jobs-title" tabindex="0">
      <form class="forma-character-grid__surface">
        <h2 class="forma-character-grid__text" id="character-grid-selection-work-with-jobs-title" data-forma-row="1" data-forma-col="23" data-forma-len="14" data-forma-emphasis="intensified">WORK WITH JOBS</h2>
        <p class="forma-character-grid__text" data-forma-row="3" data-forma-col="2" data-forma-len="26">Type options, press Enter.</p>
        <p class="forma-character-grid__text" id="character-grid-selection-work-with-jobs-legend" data-forma-row="4" data-forma-col="4" data-forma-len="30">2=Hold  3=Release  4=End</p>
        <div class="forma-character-grid__table" data-forma-row="6" data-forma-col="2" data-forma-len="45" data-forma-height="4">
          <table data-forma-gutter="2">
            <caption>Active jobs, with a selection option per row</caption>
            <thead><tr><th scope="col" id="character-grid-selection-work-with-jobs-opt" data-forma-len="3">Opt</th><th scope="col" data-forma-len="10">Job</th><th scope="col" data-forma-len="10">User</th><th scope="col" data-forma-len="14">Status</th></tr></thead>
            <tbody>
            <tr><td><input class="forma-character-grid__field" id="character-grid-selection-work-with-jobs-opt-1" name="opt-QPADEV0012" type="text" inputmode="numeric" pattern="[234]" maxlength="1" autocomplete="off" value="2" aria-labelledby="character-grid-selection-work-with-jobs-opt character-grid-selection-work-with-jobs-row-1" aria-describedby="character-grid-selection-work-with-jobs-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-work-with-jobs-row-1">QPADEV0012</th><td>OKAFOR</td><td>RUNNING</td></tr>
            <tr><td><input class="forma-character-grid__field" id="character-grid-selection-work-with-jobs-opt-2" name="opt-NIGHTLYGL" type="text" inputmode="numeric" pattern="[234]" maxlength="1" autocomplete="off" aria-labelledby="character-grid-selection-work-with-jobs-opt character-grid-selection-work-with-jobs-row-2" aria-describedby="character-grid-selection-work-with-jobs-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-work-with-jobs-row-2">NIGHTLYGL</th><td>BATCHSYS</td><td>WAITING</td></tr>
            <tr><td><input class="forma-character-grid__field" id="character-grid-selection-work-with-jobs-opt-3" name="opt-RPTAGING" type="text" inputmode="numeric" pattern="[234]" maxlength="1" autocomplete="off" value="4" aria-labelledby="character-grid-selection-work-with-jobs-opt character-grid-selection-work-with-jobs-row-3" aria-describedby="character-grid-selection-work-with-jobs-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-work-with-jobs-row-3">RPTAGING</th><td>RIVERA</td><td>HELD</td></tr>
            </tbody>
          </table>
        </div>
        <p class="forma-character-grid__message" id="character-grid-selection-work-with-jobs-message" role="status" data-forma-severity="information" data-forma-row="10" data-forma-col="2" data-forma-len="58"><span class="forma-character-grid__severity"><span>INFO</span></span> Press Enter to process the options you typed.</p>
        <div class="forma-character-grid__group" role="group" aria-label="Function keys">
          <button class="forma-character-grid__key" type="submit" name="action" value="enter" data-forma-action="enter" data-forma-row="11" data-forma-col="2" data-forma-len="13"><kbd>Enter</kbd>=Process</button>
          <button class="forma-character-grid__key" type="submit" name="action" value="f3" formnovalidate data-forma-action="f3" data-forma-row="11" data-forma-col="17" data-forma-len="7"><kbd>F3</kbd>=Exit</button>
          <button class="forma-character-grid__key" type="submit" name="action" value="f5" formnovalidate data-forma-action="f5" data-forma-row="11" data-forma-col="26" data-forma-len="10"><kbd>F5</kbd>=Refresh</button>
        </div>
      </form>
    </div>
  </div>
</forma-character-grid-selection>

Click or tap the code once to select all of it, then copy.

Scenario

Empty result

No records match the filter, so there are no option fields. The table states the empty result in a full-width row instead of leaving blank lines, and the legend is omitted because no option can be typed.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

WORK WITH ACCOUNTS

Branch SOUTH-WEST
Accounts in branch SOUTH-WEST
OptAccountName
(No accounts match. Change the branch.)

INFO WWA010I 0 accounts in branch SOUTH-WEST.

HTML · Empty result Raw HTML for HTML · Empty result
<forma-character-grid-selection class="forma-component-tag">
  <div class="forma-character-grid" data-forma-rows="9" data-forma-columns="60" data-forma-narrow="contained">
    <div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-selection-empty-list-title" tabindex="0">
      <form class="forma-character-grid__surface">
        <h2 class="forma-character-grid__text" id="character-grid-selection-empty-list-title" data-forma-row="1" data-forma-col="21" data-forma-len="18" data-forma-emphasis="intensified">WORK WITH ACCOUNTS</h2>
        <span class="forma-character-grid__text" data-forma-row="3" data-forma-col="2" data-forma-len="11">Branch<span class="forma-character-grid__leader" aria-hidden="true">  . :</span></span>
        <span class="forma-character-grid__value" data-forma-row="3" data-forma-col="14" data-forma-len="10">SOUTH-WEST</span>
        <div class="forma-character-grid__table" data-forma-row="5" data-forma-col="2" data-forma-len="45" data-forma-height="2">
          <table data-forma-gutter="2">
            <caption>Accounts in branch SOUTH-WEST</caption>
            <thead><tr><th scope="col" data-forma-len="3">Opt</th><th scope="col" data-forma-len="14">Account</th><th scope="col" data-forma-len="24">Name</th></tr></thead>
            <tbody>
            <tr><td colspan="3">(No accounts match. Change the branch.)</td></tr>
            </tbody>
          </table>
        </div>
        <p class="forma-character-grid__message" role="status" data-forma-severity="information" data-forma-row="8" data-forma-col="2" data-forma-len="58"><span class="forma-character-grid__severity"><span>INFO</span></span> WWA010I 0 accounts in branch SOUTH-WEST.</p>
        <div class="forma-character-grid__group" role="group" aria-label="Function keys">
          <button class="forma-character-grid__key" type="submit" name="action" value="pf3" formnovalidate data-forma-action="pf3" data-forma-row="9" data-forma-col="2" data-forma-len="8"><kbd>PF3</kbd>=Exit</button>
          <button class="forma-character-grid__key" type="submit" name="action" value="pf12" formnovalidate data-forma-action="pf12" data-forma-row="9" data-forma-col="12" data-forma-len="11"><kbd>PF12</kbd>=Cancel</button>
        </div>
      </form>
    </div>
  </div>
</forma-character-grid-selection>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Option column on a phone

A narrow list on a 40-column grid. On phones each one-cell option field widens to the 44px touch minimum, which extends into its three-cell column plus two-cell gutter and never into the next column.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At the touch pitch the one-cell field grows to 2.75rem, which fits because the Opt column plus its gutter is five cells (CG-17).
  • Rows grow to 44px, so each option field is a comfortable tap target in its own row.
  • The table run keeps its columns; wider lists scroll inside the viewport instead of the page.
  • inputmode="numeric" brings up a number pad for option codes.
HTML · Option column on a phone Raw HTML for HTML · Option column on a phone
<forma-character-grid-selection class="forma-component-tag">
  <div class="forma-character-grid" data-forma-rows="8" data-forma-columns="40" data-forma-narrow="contained">
    <div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-selection-selection-mobile-title" tabindex="0">
      <form class="forma-character-grid__surface">
        <h2 class="forma-character-grid__text" id="character-grid-selection-selection-mobile-title" data-forma-row="1" data-forma-col="12" data-forma-len="16" data-forma-emphasis="intensified">WORK WITH ORDERS</h2>
        <p class="forma-character-grid__text" id="character-grid-selection-selection-mobile-legend" data-forma-row="2" data-forma-col="2" data-forma-len="22">4=Cancel  5=Display</p>
        <div class="forma-character-grid__table" data-forma-row="4" data-forma-col="2" data-forma-len="30" data-forma-height="3">
          <table data-forma-gutter="2">
            <caption>Open orders, with a selection option per row</caption>
            <thead><tr><th scope="col" id="character-grid-selection-selection-mobile-opt" data-forma-len="3">Opt</th><th scope="col" data-forma-len="8">Order</th><th scope="col" data-forma-len="10">Status</th></tr></thead>
            <tbody>
            <tr><td><input class="forma-character-grid__field" id="character-grid-selection-selection-mobile-opt-1" name="opt-SO-88412" type="text" inputmode="numeric" pattern="[45]" maxlength="1" autocomplete="off" aria-labelledby="character-grid-selection-selection-mobile-opt character-grid-selection-selection-mobile-row-1" aria-describedby="character-grid-selection-selection-mobile-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-selection-mobile-row-1">SO-88412</th><td>PICKING</td></tr>
            <tr><td><input class="forma-character-grid__field" id="character-grid-selection-selection-mobile-opt-2" name="opt-SO-88419" type="text" inputmode="numeric" pattern="[45]" maxlength="1" autocomplete="off" aria-labelledby="character-grid-selection-selection-mobile-opt character-grid-selection-selection-mobile-row-2" aria-describedby="character-grid-selection-selection-mobile-legend" data-forma-len="1"></td><th scope="row" id="character-grid-selection-selection-mobile-row-2">SO-88419</th><td>OPEN</td></tr>
            </tbody>
          </table>
        </div>
        <div class="forma-character-grid__group" role="group" aria-label="Function keys">
          <button class="forma-character-grid__key" type="submit" name="action" value="enter" data-forma-action="enter" data-forma-row="8" data-forma-col="2" data-forma-len="13"><kbd>Enter</kbd>=Process</button>
          <button class="forma-character-grid__key" type="submit" name="action" value="pf3" formnovalidate data-forma-action="pf3" data-forma-row="8" data-forma-col="17" data-forma-len="8"><kbd>PF3</kbd>=Exit</button>
        </div>
      </form>
    </div>
  </div>
</forma-character-grid-selection>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelledbyoption inputcolumn th id, then row th id—Required (CG-17). Names the field by its column and row headers, for example "Opt 00417-2231-09".
aria-describedbyoption inputlegend id, plus message id when invalid—The option legend describes every field; an invalid field also references the message.
maxlengthoption inputinteger—Required. Equals the field's data-forma-len, which must fit its column.
scopethcol | row—Column headers name the option column; each row header names its record.
patternoption inpute.g. [245]—Optional native expression of the valid codes. Which codes are valid is application policy.
aria-invalidoption inputtrueabsentSet by the application on rows it rejected after Enter.
disabledoption inputbooleanabsentA row that cannot take options, such as a closed account. Skipped by Tab.
colspantdinteger—Lets an explicit empty-result row span the table; it wraps normally.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-character-grid__tableElement class—The positioned run holding the table. Its caption is visually hidden.
.forma-character-grid__fieldElement class—In a table cell the field is display: block and exactly data-forma-len cells wide; on narrow screens its touch minimum extends into the gutter.
[data-forma-len]Attribute hook—On th[scope=col]: column width in cells. On the field: its width, equal to maxlength.
[data-forma-gutter]Attribute hook—On the table: cells between columns (0-4). The option column plus gutter must be at least five cells for a field shorter than five.
[data-forma-height]Attribute hook—Rows the table run occupies, header included.
[data-forma-align]Attribute hook—end on a column header or cell for amounts.
[aria-invalid]Attribute hook—true draws the dashed invalid cue on a rejected row's field.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves down and up the option column in row-major order, skipping disabled rows natively, then on to the keys.
TypingEnters an option code, stopped at maxlength.
EnterNative implicit submission through the first submit key; the application processes the changed rows.
Events
EventDescription
submitNative form event. The application compares each option field with its initial value (the 5250 READC idiom) and validates the changed rows.

Form behavior

Each option field submits as its own named value, conventionally named after its record (opt-<record id>). Disabled rows do not submit.

States

Character grid selection states
StateHow it is expressedPresentation
Empty optionno valueField surface with a solid underline, waiting for a code.
Option typedvalue set by the userThe code is shown in the field until the application processes it.
Rejectedaria-invalid="true" plus a message referenceDashed rules above and below; the message explains the valid codes.
Unavailable rowdisabledDotted underline and muted text; skipped by Tab.
Empty lista single td colspan rowThe empty result is stated in words; no fields are rendered.

Accessibility

Forma provides

  • Keeps native table semantics and native inputs, so screen readers announce the record and column with each field.
  • Keeps each field exactly its cells wide while giving it a 44px touch target on phones inside its own column.
  • Uses the shape-based field cues, which survive forced colors.

Your application supplies

  • Name every field with aria-labelledby pointing to the column header and the row header, and describe it with the legend.
  • On Enter, validate only the changed rows; set aria-invalid and the message ID on rejected rows and move focus to the first one.
  • Clear processed options, or explain in the message what happened to them.
  • State an empty list in words instead of rendering blank rows.

Responsive behavior

  • The table run keeps its columns at every width; the viewport scrolls horizontally when needed.
  • On narrow or coarse-pointer screens, fields shorter than five cells extend into the column and gutter to reach 2.75rem (CG-17).
  • Automatic table layout makes th[data-forma-len] widths minimums, so text-spacing overrides widen a column instead of overlapping the next.

Motion

  • No animation: fields, states and rows change immediately.

Usage guidance

Do

  • Show the legend above the list and keep codes short (one or two cells).
  • Name each field after its record so submitted data identifies the row.

Avoid

  • Putting the option field outside the table or styling a cell to look like a field.
  • Global single-letter shortcuts for options; typing in a field is the input path.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.