Shopify Range Setting: Los het foutbericht '101 Steps' op

De foutmelding "Range settings must have at most 101 steps" betekent dat je combinatie van min, max en step meer dan 101 mogelijke schuifposities oplevert. Los het op door step groter te maken, max te verlagen of over te schakelen naar het number invoertype wanneer je echt een groot numeriek bereik nodig hebt. De oorzaak is altijd rekenkundig, geen bug.

Belangrijkste punten

• Shopify beperkt range settings tot maximaal 101 stappen (afgedwongen bij het parseren van het schema).
• Het aantal stappen wordt berekend als (max - min) / step. Dit resultaat mag 100 of lager zijn.
• De fout verschijnt in de Shopify theme editor en voorkomt dat het section wordt weergegeven.
• Het veranderen van step: 1 naar een hoger getal is meestal de snelste oplossing.
• Wanneer je een ongelimiteerde integer-invoer nodig hebt, vervang je range door number.

Wat is de 101-stappen regel?

Shopify's range invoertype rendert een schuifregelaar in de theme editor. Het platform handhaaaft een harde limiet: de schuifregelaar kan maximaal 101 posities hebben (stappen 0 tot en met 100, inclusief). Shopify berekent het aantal stappen intern als:

steps = (max - min) / step

Als deze berekening resulteert in een waarde groter dan 100, wijst Shopify het schema af en geeft:

Error: Invalid schema: setting with id="[your_id]" step invalid.
Range settings must have at most 101 steps.

Deze validatie wordt elke keer uitgevoerd wanneer de theme editor het section laadt, dus het section wordt volledig onbruikbaar totdat het schema is gecorrigeerd.

Opmerking: Zoals Shopify bevestigde in hun documentatie over invoer-instellingen, moeten alle vier range-attributen (min, max, step, default) numerieke waarden zijn, geen strings. Het doorgeven van een string voor een van deze waarden geeft ook een foutmelding.

De drie meest voorkomende triggers

Dit zijn de patronen die ik het vaakst zie wanneer merchants of junior developers tegen deze muur aanlopen:

1. Groot bereik met step: 1. Het instellen van min: 0, max: 500, step: 1 levert 500 stappen op. Dit is het meest voorkomende geval.
2. Het verhogen van een bestaande max zonder step aan te passen. Een developer wijzigt max van 100 naar 300 op een logo-breedteschuif, maar vergeet dat de step op 1 blijft.
3. Een range uit een HTML spec-voorbeeld kopieren. HTML standaard staat elk aantal stappen toe. Shopify niet.

Echte communityvoorbeelden zijn onder meer een free_shipping_threshold schuif ingesteld op min: 0, max: 500, step: 1 en een logo_max_width schuif verhoogd van 300px naar 550px zonder de step opnieuw te berekenen.

Hoe bereken je of je range geldig is

Voordat je een regel schema schrijft, voer je deze controle uit:

(max - min) / step <= 100   →  geldig
(max - min) / step > 100    →  geeft de 101-stappen fout

Snelle voorbeelden

De grens is exact 100 berekende stappen (wat 101 schuifposities geeft, inclusief het startpunt). Elke waarde boven 100 wordt afgewezen.

Drie manieren om het op te lossen

1. Verhoog de stapwaarde

Dit is in de meeste gevallen de juiste oplossing. Een opvulschuif die van 0 naar 200px in stappen van 2 gaat, geeft merchants 101 posities en blijft binnen de limiet.

{
  "type": "range",
  "id": "section_padding",
  "label": "Section padding",
  "min": 0,
  "max": 200,
  "step": 2,
  "unit": "px",
  "default": 40
}

Wanneer te gebruiken: Bijna altijd. De meeste ontwerpwaarden (opvulling, lettergrootten, opaciteitspercentages) hebben geen precisie van enkele eenheden over een groot bereik nodig.

2. Verlaag de maximale waarde

Als precisie met enkele stappen belangrijk is (bijvoorbeeld een 1-tot-5 sterrenclassificatie of een 0-tot-100 percentage), verlaag je max eenvoudig om binnen 100 stappen bij step: 1 te blijven.

{
  "type": "range",
  "id": "free_shipping_threshold",
  "label": "Free shipping threshold",
  "min": 0,
  "max": 100,
  "step": 1,
  "unit": "$",
  "default": 50
}

Deze door de community geverifieerde oplossing was de aanvaarde oplossing voor het free_shipping_threshold geval dat zich verspreidde over de Shopify forums.

3. Wissel naar het number type

Wanneer je echt een merchant nodig hebt om elk geheel getal in te voeren (een animatievertraging in milliseconden, een productaantal boven 100, een drempel die 0-9999 kan zijn), is het range type helemaal niet het juiste hulpmiddel. Gebruik in plaats daarvan number.

{
  "type": "number",
  "id": "free_shipping_threshold",
  "label": "Free shipping threshold ($)",
  "default": 50
}

Het number type accepteert elk geheel getal, heeft geen schuifregelaar-limiet en is in Liquid identiek toegankelijk via section.settings.free_shipping_threshold. Het compromis is een tekstinvoer in plaats van een schuif, dus merchants kunnen waarden buiten het bereik invoeren. Als bewaking belangrijk is, voeg je een Liquid-controle in je sectie-code toe.

De juiste oplossing kiezen: een beslissingstabel

Iets dat veel tutorials overslaan: range ondersteunt alleen gehele getallen

Shopify's range-invoer ondersteunt geen decimale stapwaarden. Als je een stapwaarde van 0.1 nodig hebt voor opaciteit, is de oplossing om de waarde als geheel getal (0 tot 100) op te slaan en door 100 in je Liquid-uitvoer te delen:

{% assign opacity = section.settings.overlay_opacity | divided_by: 100.0 %}
<div style="opacity: {{ opacity }}">

Dit patroon ziet er netter uit dan het lijkt: de merchant ziet een 0-100 schuif, je CSS krijgt een 0,0-1,0 float. Geen hacks nodig.

Je oplossing controleren voordat je publiceert

Theme Check, Shopify's officiële linting CLI, vangt deze fout op tijdens lokale ontwikkeling. Voer het uit voordat je schema-wijzigingen pusht:

shopify theme check

Als je rechtstreeks in de Shopify admin code editor werkt (zonder lokale CLI-setup), sla je het section bestand op en laad je de theme editor preview opnieuw. De fout verschijnt als een rood banner bovenaan de customizer als het schema nog steeds ongeldig is.

Voor een dieper inzicht in hoe Theme Check schema-validatie en argumentfouten verwerkt, zie Shopify Theme Check: Why a Single File Path Argument Does Not Work.

Praktische checklist voordat je een range setting toevoegt

Gebruik deze lijst elke keer wanneer je een nieuw range blok schrijft:

• Bereken (max - min) / step en bevestig dat het resultaat 100 of lager is.
• Bevestig dat alle vier attributen (min, max, step, default) gehele getallen zijn, geen strings.
• Bevestig dat default tussen min en max valt.
• Vraag jezelf af: heeft deze waarde echt baat bij een schuif? Zo niet, gebruik number, select of text.
• Test in de theme editor voordat je naar productie pusht.

Voor een compleet overzicht van elk schema invoertype en wanneer elk te gebruiken, zie de Shopify theme development gids.

Samenvatting

De fout "range parameters must have at most 101 steps" is zuivere rekenkunst. De formule (max - min) / step moet 100 of minder opleveren. Maak je stap breder, beperk je max of wissel naar het number type. Geen van deze oplossingen vereist een Shopify plan-upgrade, een thema-herstelling of een ondersteuningsticket. Begrijp de beperking eenmaal en je zult er nooit meer tegen aanlopen.