> ## 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.

# Dynamic Lookup Widget

> Create dynamic dropdowns with values that change based on conditions

<img src="https://mintcdn.com/clearcalcs/Frl-BqFiuGxMu3Iv/images/migrated/823f9ecf6ce8-mafi-20solar-20calculator-20-valid-20and.gif?s=b98f4740e4bbd99f8969b755a7dfb6c3" alt="Dynamic Lookup Demo" width="840" height="512" data-path="images/migrated/823f9ecf6ce8-mafi-20solar-20calculator-20-valid-20and.gif" />

Dynamic Lookup Widgets are a powerful tool for allowing users to select values from a predefined set of options that can change based on conditions or other inputs. This guide walks through setting up and using dynamic lookup widgets.

## Setup Process

### 1. Creating the Options Data

<Steps>
  <Step title="Create a Equation Widget">
    Start by creating an equation widget or equation widget to store your options data
  </Step>

  <Step title="Structure Data as a Matrix">
    Organize your data in a matrix format, where each option set is separated into rows

    **Example format**: `[[A,a], [B,b], [C,c]]`
  </Step>
</Steps>

The Equation Widget would look like this:

<img src="https://mintcdn.com/clearcalcs/7GJyORIkCuwKrW7N/images/migrated/296cecc46ab3-image.png?fit=max&auto=format&n=7GJyORIkCuwKrW7N&q=85&s=e88d81f41141bdb4904091ff9436ced1" alt="Options Data Setup" width="809" height="551" data-path="images/migrated/296cecc46ab3-image.png" />

### 2. Setting Up the Dynamic Widget

<Steps>
  <Step title="Create the Dynamic Widget">
    Add a new dynamic lookup widget to your template
  </Step>

  <Step title="Link Data Source">
    In the data source field, input the ID of the equation widget you created in step 1. This ensures the dynamic widget pulls its options from the correct source
  </Step>
</Steps>

<img src="https://mintcdn.com/clearcalcs/0BKfHfJWdoXOtU8o/images/migrated/d862d0e25540-image.png?fit=max&auto=format&n=0BKfHfJWdoXOtU8o&q=85&s=a5af5c2b3176fbe2adf13b72150f1795" alt="Data Source Configuration" width="904" height="121" data-path="images/migrated/d862d0e25540-image.png" />

### 3. Setting the Default Value

<Steps>
  <Step title="Select Default Value">
    Decide on a default value that should be presented to the user initially
  </Step>

  <Step title="Use matrixSubset">
    Use `matrixSubset` to select the first value from the matrix created in the equation widget

    **Example**: `matrixSubset(t_avail, 0, 0)` selects the first element
  </Step>
</Steps>

<img src="https://mintcdn.com/clearcalcs/E_1kb1vSSHohKQJH/images/migrated/600caae7a5df-image.png?fit=max&auto=format&n=E_1kb1vSSHohKQJH&q=85&s=5dc617436a0b04143babcd629a1481ff" alt="Default Value Setup" width="602" height="130" data-path="images/migrated/600caae7a5df-image.png" />

This formula selects the first element from the `t_avail` matrix to be the default value.

### 4. Testing and Final Adjustments

<Steps>
  <Step title="Thorough Testing">
    Test the widget extensively to confirm that values are displayed correctly according to the conditions you've set
  </Step>

  <Step title="Hide Equation Widget">
    Hide the equation widget to prevent user confusion and ensure a clean user interface
  </Step>

  <Step title="Make Adjustments">
    If any issues are identified during testing, make necessary adjustments to formulas, connections, or settings
  </Step>
</Steps>

## Data Structure Examples

### Simple Options Matrix

```javascript theme={null}
[
  ["Option 1", "value1"],
  ["Option 2", "value2"], 
  ["Option 3", "value3"]
]
```

### Conditional Options Matrix

```javascript theme={null}
// Based on material type
material_type == "steel" ? [
  ["S275", 275],
  ["S355", 355],
  ["S420", 420]
] : [
  ["C20/25", 20],
  ["C25/30", 25],
  ["C30/37", 30]
]
```

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Material Selection" icon="packages">
    Different materials available based on design code or region
  </Card>

  <Card title="Section Properties" icon="ruler">
    Available cross-sections filtered by material or size constraints
  </Card>

  <Card title="Load Factors" icon="weight">
    Load combination factors that vary by building type
  </Card>

  <Card title="Code Parameters" icon="book">
    Design parameters that change based on selected standard
  </Card>
</CardGroup>

## Best Practices

<Tip>
  * Always provide a sensible default value using `matrixSubset`
  * Hide the data source equation widget to keep the interface clean
  * Test all possible conditions that affect the dropdown options
  * Use descriptive labels for both display text and underlying values
  * Consider performance impact with very large option sets
  * Document the data structure in `authorNotes` for future developers
</Tip>

<Warning>
  Ensure your data matrix structure is consistent across all conditions. Inconsistent matrix shapes can cause errors when the dynamic lookup widget tries to process the data.
</Warning>

## Matrix Functions

### Common Matrix Operations

* **`matrixSubset(matrix, row, col)`** - Extract specific values
* **`matrixLength(matrix)`** - Get number of rows
* **`matrixColumn(matrix, col)`** - Extract entire column
* **`matrixRow(matrix, row)`** - Extract entire row

### Example Implementation

```javascript theme={null}
// Data source widget (hidden)
material_type == "steel" ? [
  ["S275", 275, 430],
  ["S355", 355, 510] 
] : [
  ["C20/25", 20, 25],
  ["C25/30", 25, 30]
]

// Default value in dynamic lookup
matrixSubset(material_options, 0, 0)  // First option display text

// Accessing selected values in other widgets  
matrixSubset(material_options, selected_index, 1)  // Yield strength
matrixSubset(material_options, selected_index, 2)  // Ultimate strength
```