# How to Use the instruction_steps Array for UI Display in the Exercises Dataset

> Learn how to use the instruction_steps array for UI display in the exercises dataset. Render step-by-step instructions directly in your app.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Yes, the `instruction_steps` array is specifically designed as an ordered list of step-by-step instructions for direct UI rendering across multiple languages.**

The `hasaneyldrm/exercises-dataset` repository provides a structured fitness dataset where each exercise includes an `instruction_steps` object that stores localized instruction arrays. This format eliminates the need to parse long text paragraphs, allowing you to render numbered lists, carousels, or collapsible panels directly from the JSON data.

## Understanding the instruction_steps Data Structure

The dataset stores multilingual instructions in two complementary formats within each exercise object in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json). The `instruction_steps` field contains an object with language keys mapping to ordered string arrays.

The supported language keys include: `en`, `es`, `it`, `tr`, `ru`, `zh`, `hi`, `pl`, `ko`, and `fr`. Each key contains an array where index 0 represents step one, index 1 represents step two, and so on, guaranteeing deterministic ordering for UI consumption.

As defined in the [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) file and documented in the README, this structure exists alongside the legacy `instructions` string field, which provides the same content as a single paragraph for backward compatibility.

## Why Use instruction_steps for UI Rendering

**Consistent ordering** – The array indices explicitly define the sequence of movements, eliminating ambiguity about which action comes first when rendering step-by-step guides.

**Internationalization-ready** – Every language follows the identical array structure, allowing you to switch locales by changing the object key (e.g., `instruction_steps.es` to `instruction_steps.fr`) without modifying your UI rendering logic.

**Framework compatibility** – Modern frontend frameworks including React, Vue, and Angular natively support mapping over string arrays to generate list elements, reducing transformation overhead.

## Implementation Examples by Platform

### React Component Implementation

The following TypeScript component demonstrates type-safe access to the `instruction_steps` array:

```tsx
import React from "react";
import exercises from "../data/exercises.json";

type Props = {
  exerciseId: string;
  language: keyof typeof exercises[0]["instruction_steps"];
};

export const InstructionSteps: React.FC<Props> = ({ exerciseId, language }) => {
  const exercise = exercises.find((e) => e.id === exerciseId);
  if (!exercise) return null;

  const steps = exercise.instruction_steps[language];

  return (
    <ol>
      {steps.map((step, idx) => (
        <li key={idx}>{step}</li>
      ))}
    </ol>
  );
};

```

### Vanilla JavaScript (Browser/Node)

For environments without framework overhead, iterate directly over the array:

```javascript
import exercises from "./data/exercises.json";

// Access English steps for the first exercise
const enSteps = exercises[0].instruction_steps.en;

// Render as an ordered list
const ul = document.createElement("ul");
enSteps.forEach(step => {
  const li = document.createElement("li");
  li.textContent = step;
  ul.appendChild(li);
});
document.body.appendChild(ul);

```

### Python with Pandas

When analyzing the dataset in data science workflows, use `pd.json_normalize` to flatten the nested structure:

```python
import json
import pandas as pd

with open("data/exercises.json", encoding="utf-8") as f:
    data = json.load(f)

df = pd.json_normalize(data, sep="_")

# Retrieve English steps for exercise "0001"

steps = df.loc[df.id == "0001", "instruction_steps_en"].iloc[0]
for i, step in enumerate(steps, 1):
    print(f"{i}. {step}")

```

### Swift (iOS)

For native iOS applications, decode the nested dictionary structure directly:

```swift
struct Exercise: Decodable {
    let id: String
    let instruction_steps: [String: [String]]
}

// Load from bundle
let url = Bundle.main.url(forResource: "exercises", withExtension: "json")!
let data = try Data(contentsOf: url)
let exercises = try JSONDecoder().decode([Exercise].self, from: data)

// Display English steps
let steps = exercises.first!.instruction_steps["en"]!
// Use steps array to populate UITableView or SwiftUI List

```

## Key Source Files and References

- **[`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json)** – Contains 1,324 exercise objects with the `instruction_steps` field for all supported languages.
- **[`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json)** – JSON Schema formally defining the `instruction_steps` structure and language key constraints.
- **[`index.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html)** – Reference implementation showing how the dataset renders instructions in a browser interface.
- **[`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html)** – Developer documentation for importing and accessing the dataset from various programming languages.
- **[`README.md`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/README.md)** – Complete data model documentation including the `instruction_steps` specification at line 93.

## Summary

- The `instruction_steps` array provides **ordered, language-specific instruction sequences** ideal for UI step lists.
- **Ten languages** are supported under consistent object keys within each exercise record.
- The format integrates directly with React, Vue, Angular, Swift, and Python without requiring text parsing or string splitting.
- Source files [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) and [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) provide the authoritative structure and validation rules.

## Frequently Asked Questions

### What is the difference between instructions and instruction_steps?

The `instructions.<lang>` property contains a single string paragraph describing the exercise, while `instruction_steps.<lang>` provides the same content split into an ordered array of individual steps. Use the string format for simple text displays and the array format when you need to render numbered lists or step-by-step walkthroughs.

### Which languages are supported in the instruction_steps array?

The dataset includes `instruction_steps` for English (`en`), Spanish (`es`), Italian (`it`), Turkish (`tr`), Russian (`ru`), Chinese (`zh`), Hindi (`hi`), Polish (`pl`), Korean (`ko`), and French (`fr`). Each exercise contains all ten language keys when translations are available.

### How do I handle missing translations in instruction_steps?

According to the schema in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json), the `instruction_steps` object requires all supported language keys to be present. If a specific translation is missing, the array typically contains the English fallback or an empty array, depending on the dataset version. Always verify array length before rendering or implement a fallback to `instruction_steps.en`.

### Is the instruction_steps array suitable for accessibility features?

Yes, the ordered array structure is ideal for accessibility implementations. You can map each array element to `<li>` elements within an `<ol>` tag in HTML, which screen readers announce with proper step numbering. The deterministic ordering also supports voice navigation commands like "next step" or "previous step" in assistive technologies.