@bafv4/mcitems

Minecraft item data, textures, and translations for React and Vue applications with multi-version support.

Installation

# From GitHub
pnpm add github:bafv4/mcitems
# Or with a specific tag
pnpm add github:bafv4/mcitems#v2.0.0

Features

• Multi-Version Support: Separate modules for different Minecraft versions
• Item Data: Complete list of Minecraft items organized by Creative Inventory categories
• Textures: PNG textures for all items and blocks
• Translations: All 125 official Minecraft languages (en_us + ja_jp bundled, others loadable on demand)
• React Component: MinecraftItemIcon for displaying item icons
• Vue Component: MinecraftItemIcon for Vue 3 applications
• Potion Effects: Full support for potion effect variants
• Framework Independent: React and Vue are optional peer dependencies

Supported Versions

Version	Import Path	Status
1.16.x	@bafv4/mcitems/1.16	Supported
1.20.x	@bafv4/mcitems/1.20	Coming Soon
1.21.x	@bafv4/mcitems/1.21	Coming Soon

Usage

React

import{MinecraftItemIcon,getAllItems}from'@bafv4/mcitems/1.16/react';// Basic usage<MinecraftItemIconitemId="minecraft:diamond_sword"size={48}/>// With potion effect<MinecraftItemIconitemId="minecraft:potion"nbtData={{Potion: 'minecraft:fire_resistance'}}size={32}/>// With custom texture base URL<MinecraftItemIconitemId="minecraft:iron_pickaxe"textureBaseUrl="/assets/mcitems"size={48}/>// Using data functionsconstitems=getAllItems();

Vue

<script setup lang="ts">import { MinecraftItemIcon, getAllItems } from'@bafv4/mcitems/1.16/vue';const items =getAllItems();</script>
<template>
<!-- Basic usage -->
<MinecraftItemIcon itemId="minecraft:diamond_sword" :size="48" />
<!-- With potion effect -->
<MinecraftItemIcon
itemId="minecraft:potion"
:nbtData="{ Potion: 'minecraft:fire_resistance' }"
:size="32"
/>
<!-- With custom texture base URL -->
<MinecraftItemIcon
itemId="minecraft:iron_pickaxe"
textureBaseUrl="/assets/mcitems"
:size="48"
/>
</template>

Core Functions Only (No Framework)

import{getAllItems,formatItemName,MINECRAFT_VERSION}from'@bafv4/mcitems/1.16';console.log(MINECRAFT_VERSION);// "1.16"constitems=getAllItems();constname=formatItemName('minecraft:diamond_sword');

Item Data Functions

import{getAllItems,getItemsByCategory,getCraftableItems,searchItems,formatItemName,ITEM_CATEGORIES,}from'@bafv4/mcitems/1.16';// Get all itemsconstitems=getAllItems();// Get items by categoryconsttools=getItemsByCategory('tools');// Get craftable items only (for recipe search)constcraftable=getCraftableItems();// Search items (by ID or display name in the given language)constresults=searchItems('diamond');constjaResults=searchItems('ダイヤ');// Japanese works too// Format item name (Japanese by default)constname=formatItemName('minecraft:diamond_sword');// => 'ダイヤモンドの剣'// Available categoriesITEM_CATEGORIES.forEach(cat=>{console.log(cat.id,cat.name);});

Translations (125 Languages)

Item names are available in every official Minecraft language. en_us and ja_jp are bundled; other languages are loaded at runtime or bundled explicitly.

import{getItemName,formatItemName,loadLang,registerLang,isLangLoaded,getCategoryName,getEffectName,AVAILABLE_LANGS,// all 125 language codesBUNDLED_LANGS,// ['en_us', 'ja_jp']}from'@bafv4/mcitems/1.16';// Bundled languages work synchronously out of the boxgetItemName('minecraft:diamond_sword','ja_jp');// => 'ダイヤモンドの剣'getItemName('minecraft:diamond_sword');// => 'Diamond Sword' (en_us)// Potion variant IDs resolve to full vanilla namesgetItemName('minecraft:splash_potion.fire_resistance','ja_jp');// => '耐火のスプラッシュポーション'// Load any other language at runtime (see "Language File Setup" below)awaitloadLang('de_de','/mcitems');getItemName('minecraft:diamond_sword','de_de');// => 'Diamantschwert'// formatItemName always returns a string (lang → en_us → Title Case fallback)formatItemName('minecraft:diamond_sword','de_de');// => 'Diamantschwert'// Category (creative tab) and status effect namesgetCategoryName('brewing','ja_jp');// => '醸造'getEffectName('minecraft:night_vision','en_us');// => 'Night Vision'

Alternatively, bundle a language into your app instead of fetching it:

// Bundlers (Vite / webpack / Next.js) handle the JSON import as-is:importkoKrfrom'@bafv4/mcitems/1.16/lang/ko_kr';// Plain Node.js ESM requires the import attribute instead:// import koKr from '@bafv4/mcitems/1.16/lang/ko_kr' with { type: 'json' };import{registerLang,getItemName}from'@bafv4/mcitems/1.16';registerLang('ko_kr',koKr);getItemName('minecraft:diamond_sword','ko_kr');// => '다이아몬드 검'

Typical language-switching pattern (e.g. reacting to a user setting):

asyncfunctionsetLanguage(lang: string){awaitloadLang(lang,LANG_BASE_URL);// no-op if already loadedrerender();// all getItemName/formatItemName calls are now synchronous}

Potion Effects

import{POTION_EFFECTS,getPotionEffectInfo,formatPotionName,formatPotionEffect,}from'@bafv4/mcitems/1.16';// Get potion infoconstinfo=getPotionEffectInfo('minecraft:fire_resistance');// => { id: 'minecraft:fire_resistance', name: '火炎耐性', variant: 12, duration: '3:00' }// Format potion name (official vanilla names, language-aware)constname=formatPotionName('minecraft:splash_potion','minecraft:fire_resistance');// => '耐火のスプラッシュポーション'formatPotionName('minecraft:splash_potion','minecraft:fire_resistance','en_us');// => 'Splash Potion of Fire Resistance'// Format effect with durationconsteffect=formatPotionEffect('minecraft:long_fire_resistance');// => '火炎耐性 (8:00)'formatPotionEffect('minecraft:strong_leaping','en_us');// => 'Jump Boost (3:00)'

Texture Setup

Textures are included in dist/textures/ after building. You need to serve them statically:

Next.js

Copy textures to public/ folder:

cp -r node_modules/@bafv4/mcitems/dist/textures public/mcitems

Then use with textureBaseUrl:

<MinecraftItemIconitemId="minecraft:diamond"textureBaseUrl="/mcitems"/>

Vite (React / Vue)

Add to vite.config.ts:

import{viteStaticCopy}from'vite-plugin-static-copy';exportdefaultdefineConfig({plugins: [viteStaticCopy({targets: [{src: 'node_modules/@bafv4/mcitems/dist/textures',dest: 'assets',},],}),],});

Nuxt 3

Copy textures to public/ folder:

cp -r node_modules/@bafv4/mcitems/dist/textures public/mcitems

Then use with textureBaseUrl:

<MinecraftItemIcon
itemId="minecraft:diamond"
textureBaseUrl="/mcitems"
/>

Language File Setup

Only en_us and ja_jp are bundled in the JS build. To use loadLang(), serve the language files from dist/1.16/lang/ statically (same approach as textures). loadLang(code, baseUrl) fetches ${baseUrl}/1.16/lang/${code}.json.

Next.js / Nuxt 3

mkdir -p public/mcitems/1.16
cp -r node_modules/@bafv4/mcitems/dist/1.16/lang public/mcitems/1.16/lang

awaitloadLang('de_de','/mcitems');

Vite (React / Vue)

import{viteStaticCopy}from'vite-plugin-static-copy';exportdefaultdefineConfig({plugins: [viteStaticCopy({targets: [{src: 'node_modules/@bafv4/mcitems/dist/1.16/lang',dest: 'mcitems/1.16'},],}),],});

awaitloadLang('de_de','/mcitems');

Regenerating Language Files (maintainers)

pnpm run gen-lang # downloads official 1.16.5 lang files from Mojang and rebuilds src/assets/lang/

Item Categories

ID	Name
all	すべて
building_blocks	建築ブロック
decorations	装飾ブロック
redstone	レッドストーン
transportation	交通
miscellaneous	雑貨
foodstuffs	食料
tools	道具
combat	戦闘
brewing	醸造

API Reference

Components

• MinecraftItemIcon (React) - React component for displaying item icons (@bafv4/mcitems/1.16/react)
• MinecraftItemIcon (Vue) - Vue 3 component for displaying item icons (@bafv4/mcitems/1.16/vue)

Functions

• getAllItems() - Get all item IDs
• getItemsByCategory(category) - Get items by category
• getCraftableItems() - Get craftable items only
• getCraftableItemsByCategory(category) - Get craftable items by category
• searchItems(query, lang?) - Search items by ID or display name
• formatItemName(itemId, lang?) - Format item ID to display name (default: Japanese)
• getItemName(itemId, lang?) - Get item display name (default: en_us, falls back to en_us)
• getEffectName(effectId, lang?) - Get status effect display name
• getCategoryName(category, lang?) - Get creative tab display name
• loadLang(code, baseUrl?) - Fetch and register a language at runtime
• registerLang(code, dict) - Register an imported language dictionary
• isLangLoaded(code) - Whether a language is ready for synchronous lookup
• getLangUrl(code, baseUrl?) - Get language file URL
• getItemNameJa(itemId) - Get Japanese translation (deprecated: use getItemName(id, 'ja_jp'))
• getTextureUrl(itemId, nbtData, baseUrl) - Get texture URL
• getPotionEffectInfo(effect) - Get potion effect info
• formatPotionName(itemId, effect, lang?) - Format potion display name
• formatPotionEffect(effect, lang?) - Format effect with duration

Constants

• MINECRAFT_VERSION - Version string (e.g., "1.16")
• TEXTURE_PATH - Texture path pattern (e.g., "1.16.1/items")
• LANG_PATH - Language file path pattern ("1.16/lang")
• AVAILABLE_LANGS - All 125 language codes
• BUNDLED_LANGS - Languages bundled in the JS build (['en_us', 'ja_jp'])
• MINECRAFT_ITEMS - Items organized by category
• ITEM_CATEGORIES - Category definitions
• POTION_EFFECTS - Potion effect data

Types

• ItemCategory - Category type union
• MinecraftItem - Item interface
• NBTItem - NBT item structure
• PotionEffectInfo - Potion effect info interface
• LangDict - Language dictionary (Record<string, string>)

Adding New Versions

To add support for a new Minecraft version:

1. Create a new version folder: src/versions/1.20/
2. Copy and modify the data files (items.ts, potionEffects.ts, translations.ts)
3. Update TEXTURE_PATH constant for the new version
4. Add entry points to tsup.config.ts
5. Add exports to package.json

License

MIT