> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lookup Data Table

> Guide to creating lookup widgets with custom data tables defined directly in the calculator builder

## Widget Core Function

**UI Experience:** Dropdown list for the user\
**Data Organization:** Allows engineers to create selection tables directly within the calculator builder without external file dependencies.

## Key Features

* Create custom selection tables directly in the builder
* Store and access the row index of selected items
* Access entire rows of data once a user makes a selection
* Support for radio button display as an alternative to dropdowns
* Mix of numbers and strings in data tables

## Video Tutorial

<Card title="Create a Data Table Example" icon="video">
  [Watch Tutorial](https://www.loom.com/share/4e2b8789ccf842fb821a3a29c9500e2d)
  Learn how to create and configure data table lookups step by step
</Card>

## Visual Presentation

<Info>
  The data table dropdown interface allows users to select from predefined options in a dropdown list or radio button format.
</Info>

## Configuration

### Example Code

```json theme={null}
{
  "type": "sheetTemplateWidgets",
  "attributes": {
    "type": "lookup",
    "label": "Load Factor",
    "symbol": "k_f",
    "defaultValue": "0",
    "visibleIf": "",
    "enableAutosize": false,
    "radioListDisplay": false,
    "dataColumns": [
      {
        "label": "Load Type",
        "key": "loadType",
        "type": "string"
      },
      {
        "label": "Factor",
        "key": "factor",
        "type": "number"
      }
    ],
    "dataTable": [
      ["Dead Load", 1.2],
      ["Live Load", 1.6],
      ["Wind Load", 1.0],
      ["Seismic Load", 1.0]
    ],
    "referenceId": "load_factor_lookup",
    "references": "AS 1170",
    "description": "Select appropriate load factor",
    "authorNotes": "",
    "referenceImage": ""
  }
}
```

### Configuration Parameters

<ResponseField name="type" type="string" required>
  Set to "lookup" to define the widget type
</ResponseField>

<ResponseField name="enableAutosize" type="boolean" default="false">
  Whether or not to enable the autosize function on the lookup. Will only work if the table has preferred sections (not currently possible without sharedTables)
</ResponseField>

<ResponseField name="radioListDisplay" type="boolean" default="false">
  If `true`, the lookup widget will display as a set of radio buttons instead of as a dropdown list
</ResponseField>

<ResponseField name="dataColumns" type="array" required>
  [Lookup Column Object](https://github.com/ClearCalcs/dev-environment/wiki/Lookup-Column-Object) - The column labels and properties for the lookup to display
</ResponseField>

<ResponseField name="dataTable" type="matrix" required>
  The data to be displayed in the lookup, which may be a mix of numbers and strings. Index 0 will always be displayed in the dropdown itself.
</ResponseField>

## Data Column Structure

Each column in the `dataColumns` array should follow this structure:

```json theme={null}
{
  "label": "Column Display Name",
  "key": "column_key",
  "type": "string" | "number" | "boolean"
}
```

### Column Properties

<ResponseField name="label" type="string" required>
  The display name for the column header
</ResponseField>

<ResponseField name="key" type="string" required>
  The internal key used to reference this column's data
</ResponseField>

<ResponseField name="type" type="string" required>
  The data type for this column: "string", "number", or "boolean"
</ResponseField>

## Data Table Structure

The `dataTable` is a matrix where:

* Each row represents one option in the lookup
* Each column corresponds to the columns defined in `dataColumns`
* Index 0 (first column) is always displayed in the dropdown
* Data can be a mix of numbers, strings, and booleans

### Example Data Table

```json theme={null}
"dataTable": [
  ["Option 1", 1.5, true],
  ["Option 2", 2.0, false],
  ["Option 3", 1.2, true]
]
```

## Display Options

### Dropdown Display (Default)

The standard dropdown interface where users select from a list of options.

### Radio Button Display

Set `radioListDisplay: true` to display options as radio buttons instead of a dropdown. This is useful when:

* You have a small number of options (typically 2-5)
* You want all options visible at once
* The selection is a key decision point in the calculation

## Examples from Current Calculators

| Reference ID  | Calculator Link                                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| lookup (k\_4) | [Steel Beam Calculator](https://calcs.com/organisation/2ad7e5c6-8d23-416d-acb1-5487dc65150a/templates/6d7fc7ed-f6f7-4392-822b-cdee58bab93b) |

## Best Practices

1. **Column Design**: Keep the first column (index 0) as the primary identifier that users will see in the dropdown

2. **Data Organization**: Organize your data logically with the most commonly used options first

3. **Mixed Data Types**: Take advantage of the ability to mix strings and numbers in the same table

4. **Radio vs Dropdown**: Use radio buttons for 2-5 options, dropdowns for more options

5. **Clear Labels**: Use descriptive column labels that clearly indicate what each column represents

6. **Default Selection**: Set appropriate default values using row indices (starting from 0)

## Accessing Selected Data

Once a user makes a selection, you can access:

* The selected row index using the widget's `referenceId`
* Specific column values using lookup functions in equation widgets
* The entire row data for complex calculations

Example of accessing data in a equation widget:

```javascript theme={null}
// Get the selected row index
selectedIndex = @load_factor_lookup

// Access specific column data
loadType = dataTableValue(@load_factor_lookup, selectedIndex, 0)  // First column
factor = dataTableValue(@load_factor_lookup, selectedIndex, 1)    // Second column
```