Custom H5P Content Types: A Decision Framework (For When Defaults Don’t Cut It)
When Is a Custom H5P Content Type Actually Worth Building?
A client came to me a while back with a brief that sounded simple on paper. They wanted students to feel what it’s like to work a shift on a production line. Not watch a video about safety procedures. Feel the trade-offs. Make a call under pressure, watch productivity dip because they played it safe, watch safety scores tank because they didn’t.
I opened up H5P and started scrolling through the content type list. Branching Scenario, sure, that gets you decisions. Interactive Video, gets you branching too, plus some visuals. Course Presentation, fine for information delivery. None of them tracked three separate performance metrics changing in real time off the back of a decision. None of them randomised which events showed up so a student could replay the shift and get a genuinely different experience. None of them spat out a results screen with a full decision log at the end.
So I did the thing every developer says they’ll avoid until they can’t avoid it anymore. I built one.
The 20 content types and the 21st problem
Here’s the thing about H5P. Most instructional designers I talk to use the same handful of content types, over and over. Interactive Video. Course Presentation. Branching Scenario. Maybe Drag the Words if they’re feeling adventurous. That’s not laziness, by the way, it’s because those content types are genuinely good at what they do and cover most of what a course needs.
But every now and then a brief lands on your desk that none of them quite fit. And this is where things get interesting. Because when a designer hits that wall, they’ve got three choices, not one.
They can bend the brief to fit an existing content type.
They can combine two or three existing content types and stitch the experience together.
Or they can build something new.
Most of the time, the answer should be one of the first two. I want to be upfront about that before I get to the fun bit, because building a custom content type is the most expensive option on the list, and it’s not close.
What I actually built
Using the H5P CLI, I scaffolded a new content type from scratch. That gives you a semantics.json file, which is basically the form your content author fills in when they build an activity, and a JavaScript file where you write the actual logic.
For the Workplace Simulation, the semantics.json defines the scenario briefing, a pool of workplace events, a set of response options for each event, and how each option nudges the three metrics up or down. The JavaScript side handles picking a random subset of events each playthrough, updating the metrics live as students choose, showing feedback after each decision, and building the results screen at the end.
None of that is exotic code. It’s state management and some conditional logic. But it’s the kind of thing that simply has no home inside an existing content type’s data structure. You can’t shoehorn “three metrics tracked across a randomised event pool” into Branching Scenario’s semantics, not without rewriting half of it anyway. At that point you’re not customising a content type, you’re building one with extra steps.
The decision framework
So how do you know, before you sink a week into scaffolding a new content type, whether you actually need one? I’ve landed on five questions I run through every time now.
Does the brief need state that persists and changes across the activity? If a student’s choices need to accumulate into something, like a score, a set of metrics, an inventory, rather than just branch to the next screen, no existing content type handles that well.
Would combining two or three existing content types get you 80% of the way there? Interactive Book plus Branching Scenario plus a Course Presentation summary screen can fake a lot of what feels like custom functionality. Try that combination first. Seriously.
Is this reusable, or is it a one off? A custom content type is only worth the build time if other teachers can reuse it with their own content. If the answer is “just this one scenario, just this once,” you’re better off hardcoding a simpler interactive video or presentation and moving on.
Do you have the ongoing capacity to maintain it? This is the one people forget. A content type isn’t done when it ships, it’s done when H5P Core updates and it still works, when a teacher finds a bug eighteen months from now, when someone asks for a feature. If you’re not around to maintain it, don’t build it.
Does the value of the activity depend on the mechanic itself? For the Workplace Simulation, the whole point was watching metrics respond to a decision in real time. That mechanic wasn’t a nice to have, it was the entire learning experience. If your custom mechanic is decorative rather than load bearing, skip it.
If your brief clears all five, build it. If it stumbles on two or more, go back to combining existing content types. You’ll save yourself a lot of semantics.json.
It’s not about the code
Here’s what I have learnt building this thing. It was never really about proving I could scaffold a content type with the CLI. Any instructional designer with a bit of programming experience can do that in an afternoon.
The actual skill is knowing when not to.
Most of the interesting decisions in this work happen before you open a code editor. They happen when you’re staring at a brief, working out whether the thing being asked for is a genuinely new mechanic, or just an old mechanic wearing a different scenario’s clothes.
Build the twenty-first content type when you need it. Just make sure you actually need it.
Custom H5P content type