You finish teaching props. You drew the box diagram, you gave examples. And they got it — you ask a question in class, they answer it fine.
Next week, in the homework, the same student asks: "how do I know where this total comes from?"
He didn't forget what you said. He knows what props are. He just can't call on it inside real code.
The box diagram got him to "I understand." It doesn't reach "I can use it." That part was never in range of an explanation.
The thing I want to say first
Your teaching is fine. They really do understand.
The problem is the next step. There's a distance between understanding and using, and that distance doesn't close with a better explanation.
props, context, .map(), conditional rendering, module structure — these are relational, not factual. "useState returns an array" is a fact. Say it once, done. "This line of JSX corresponds to that thing on screen" is a mapping. Mappings only get built by matching them up, over and over.
You can explain a mapping beautifully. They'll understand it. But understanding a mapping and being able to call on it instantly are two different things.
This isn't about teaching skill. Explanation has a ceiling, and the ceiling is at "understand." Getting past it takes reps from the student — and whether they get reps depends on whether they have something they can poke at.
So: four places this shows up every term. In all four, the students understood you. They still got stuck.
One: your first class gets eaten by environment setup
Thirty people. The lesson plan says "get a React project running."
What actually happens: five have the wrong node version. Three hit npm permission errors on Windows. Two are behind a corporate network that won't install packages. One installed nvm into the wrong shell config. You spend forty minutes doing tech support and the last twenty rushing through half your material.
What it actually costs you:
Your class time goes to something that has nothing to do with React. And you pay it again with every new cohort.
You end up maintaining a setup guide doc. Every time node, npm, or vite moves, you update it. Unpaid, forever.
You can't assign "go run this at home," because half the class gets stuck and then your weekend is answering setup questions.
And the quiet one: you filtered people out in week one, on a criterion that has nothing to do with React. The ones who dropped weren't bad at React. They just couldn't get an environment running yet. But they'll read that failure as "I'm not cut out for this."
What changes it: opening a real project costs about as much as opening a webpage. No install, no dev server — the compile happens in the browser, so there's nothing on their machine to go wrong. Which means the goal of your first class can actually be "read the structure of a real project" instead of "get thirty laptops to agree with each other." (how that works)
Someone always asks: so they never learn to set up an environment? They do. But setup is a standalone skill you can teach in week five, on purpose, with your attention on it. Putting it in week one as a gate is just a sequencing mistake.
Two: they understood props. They still can't use props.
A student can read <AnalyticsWidgetSummary total={714000} color="warning" /> and tell you what every part does. He can define props correctly.
Ask him what happens if you change total — he pauses. Ask where color="warning" is actually defined — he has no direction.
He's not confused about props. The mapping just isn't reflexive yet.
Here's why explanation tops out here, and I think this is the real point of this whole post:
A diagram is you doing the mapping for them. They see the result, they understand that it holds, but they never walked it themselves.
It's the gap between reading a translation and being able to translate. Passive understanding and active recall run on different tracks. The first doesn't automatically become the second.
And there's a counterintuitive bit: the clearer you explain it, the easier it is for them to stop at "I get it" — because the quality of your explanation saved them from having to build the mapping themselves.
So investing more in making the explanation better returns less and less. Not because the method is wrong. Because that road ends there.
Which is why you keep building fancier analogies for the same concept and the results don't scale with the effort. Your part is done. The missing part isn't on your side.
What changes it: click code, the canvas highlights. Click the canvas, the code highlights — the exact JSX node, not the general area. That's not impressive technology; it's that it turns one thing you said into forty things they did. (the mechanics of that)
Something you can use next week: before you define props abstractly, have them do twenty clicks. Let them notice on their own that this text corresponds to that pixel. Give the concept its name after the operation, not as setup for it.
And the obvious objection: won't they get dependent on the tool and never learn to find files? Depends on whether the tool shows the path. If it silently navigates for them and they never look, sure, that's a crutch. If it shows the component chain it walked and which file each layer lives in, then they're seeing real structure over and over until it stops being mysterious. That's training wheels.
Three: three concepts, three lessons, everyone half-gets each one
.map(). Student asks how to change the third card. You say you're changing the template, not the third card. He understands the sentence. But his eyes see five separate cards. Accepted intellectually, not built as intuition.
Conditional rendering. He writes isVip ? A : B, then spends twenty minutes debugging branch B. His test data always goes down A. He's debugging code that isn't running, and he doesn't know it.
HOCs. He sees withAuth(withTheme(Card)) and asks what the component is. There's no single answer — it depends which layer you mean. You can say that clearly. You can't make him walk each layer himself on a whiteboard.
Here's the useful part: those three look like three different teaching problems. They're one. What's missing isn't three pieces of knowledge. It's one piece of meta-knowledge — the rendered result and the source structure aren't one-to-one, and I need to know which layer I'm looking at.
What it costs you: you treated them as three topics, built three explanations, spent three lessons. All three explanations were correct. They all understood. But the conversion to "can use it" was low on all three, because the missing piece was the same operation, not three explanations.
What changes it:
.map(): click the second card, the code selects the map expression — because there genuinely is no "second card" in the source — then drill one step further into the template inside it. They watch five things come from one line. Reverse it: cursor on the map expression, all five cards light up at once.
Conditional rendering: put the cursor on the branch that isn't currently rendering, and the canvas renders that branch on its own. No state changes, no fake test data. That student debugging for twenty minutes figures out what he's doing in two seconds.
HOCs: climb the layers one at a time, definite answer at each. "What is this component" becomes a question you can answer layer by layer. (more on how the layers are defined)
Something you can use next week: collapse three lessons into one, called "layers." Let them drill up and down first, bump into the concept themselves, then name it.
Four: they don't know what to be careful with
Students go one of two ways. Either they won't touch anything (afraid of breaking it), or they'll touch anything (no idea what it's connected to). Both make homework hard to grade — one turns in nothing, the other turns in collateral damage.
Why explanation can't quite reach this: importance isn't a static property. It's a relationship — how many things depend on this. You can accurately say "some files are more critical," and they'll agree, and it won't help them when they open an unfamiliar repo. They need a specific answer about a specific file.
What they actually need isn't being told a file is important. It's seeing eleven references light up when they change one file. Specific, countable, located. That's when importance stops being an adjective.
And here's the part I'd care most about if I were teaching: this instinct decides whether your students can handle an unfamiliar codebase after graduation. The confusion in someone's first two weeks is almost never "I don't know React." It's "I don't know where anything lives in this repo." Someone who can trace an import chain and check inbound references can onboard anywhere. Someone who only knows hooks can onboard onto the one repo they were taught on. Which of those you're producing decides how rough their first job is.
What changes it: inbound edges give that signal a shape you can point at, and they can practice it on file after file — including the references that arrive through a barrel, which a plain editor search doesn't catch. There's an even better classroom move: break an edge on purpose. Rename an export, watch which part of the graph goes red. Targeted breakage teaches faster than a correct example. (what building that graph involves)
Worth mentioning: one of the most stubborn beginner misconceptions is that an import path tells you where the code lives. Jump through three barrels in one hop to the real definition and that misconception dies immediately.
One rule you can run your syllabus through
The four pains look unrelated — a psychological gate, a visual mapping, structural layers, relational reasoning. Underneath they're the same thing:
If a concept is fundamentally a relationship or a mapping, explanation gets them to "I understand." The rest of the way to "I can use it" only happens by doing it ten times themselves.
So, a test you can apply to your own outline:
Can students use this correctly right after understanding it? Yes → factual. Explanation is the whole solution.
Or do they still need a few tries to get comfortable? → relational. Your explanation already did its job. What's missing is somewhere for them to try.
Most of the hard parts of React are the second kind. Which is why a genuinely good instructor still ends up feeling like students "know it but can't quite use it." That stretch was never in range.
Four things you could change next week
Make the goal of class one "open a real project without being scared of it." Move environment setup to week five and teach it properly.
Before defining props, twenty clicks. Name the concept after.
Merge .map(), conditional rendering, and HOCs into one lesson called layers. Operate first, name second.
Before teaching context, have them delete a provider in a real project and see what breaks and where. Then explain why it's needed.
Not replacing your explanation. Adding the part after it.
If you've taught React for a few years and students land in the same four spots every time — understood it, can't quite use it — that isn't a quality problem with your teaching. The box diagram did its job. It got them to "I understand."
The rest of that distance doesn't need a better diagram. It needs the student to have something they can try ten times themselves.
The four things above — opening a real project with no setup, clicking between code and canvas, drilling through layers, seeing what depends on what — are all things we built into CrossUI Studio, mostly for other reasons. Each one links out to its own writeup above if you want the details. Free for classroom use; if you're teaching a cohort and want it set up, get in touch.
Top comments (0)