Element-Blazor

May 30, 2026 ยท View on GitHub

NuGet Element.X

Element-Blazor is a Blazor UI component library. The project now targets element-plus/element-plus as its primary design and component baseline.

Positioning

  • A Blazor component set focused on business back-office scenarios
  • Prioritizes practical usability and development efficiency for common components
  • Evolves through demos, documentation, and real product surfaces
  • Uses Element Plus 2.14.0 as the current visual, component-matrix, and version baseline
  • Element UI 2.15.x is kept only as a historical reference

The project is currently under continuous refactoring and upgrade. See ROADMAP.md for details.

Current Status

  • Main component project: src/Components/Element.csproj
  • Optional X package: src/X/Element.X.csproj
  • Current target framework: .NET 10
  • Current alignment version line: 2.14.0-alpha.1
  • Samples and demos: template/Samples, demo
  • Community showcase: community, a DiscuzX-like Blazor community site used to demonstrate Element-Blazor in a real product surface
  • Test project: test/Element.Test
  • demo, template, and community are Git submodules. If they are not initialized, build the component library project directly; the full solution will fail because sample projects are missing.
  • .NET 10 is the baseline for the component library mainline and new projects. Legacy demo, template, and community submodules do not need a full in-place .NET 10 upgrade before P1/P2 can continue.

Naming Strategy

  • DOM/CSS classes must keep the official Element Plus contract: el-button, el-input, el-table, is-disabled, el-button--primary.
  • Public Razor components use Element Plus-style PascalCase El* names, such as <ElButton>, <ElInput>, and <ElTable>.
  • Hyphenated <el-button> is treated as a plain HTML/custom element by Razor and is not suitable as a Blazor component type. el_ is also not idiomatic for .NET, so it is not used.
  • Legacy public component names such as Button, Input, and Table are removed directly. There is no compatibility layer and no transition alias.
  • Legacy prefixed component implementation entry points have been removed. The mainline keeps no compatibility layer, transition alias, or inheritance wrapper; active implementation names are El*/Element*.

Quick Start

Initialize submodules

This repository now uses Git submodules for demo, template, and community.

  • demo: component demos and online docs data source
  • template: project templates and sample hosts
  • community: DiscuzX-like community site with frontend, admin, API, and WASM projects

For a fresh clone, use:

git clone --recurse-submodules https://github.com/Element-Blazor/Element-Blazor.git

If you already cloned the repository, run:

git submodule sync --recursive
git submodule update --init --recursive

Build the component library

If you only need to validate the component library, run:

dotnet restore src/Components/Element.csproj
dotnet build src/Components/Element.csproj

Optional packages live outside the core package. Use Element.Markdown for Markdown editor components and Element.X for AI/conversation components.

Run local samples and the full solution

  1. Open the repository with Visual Studio 2022 or dotnet CLI
  2. Make sure the demo, template, and community submodules are initialized
  3. Restore dependencies and build the solution
  4. Start a sample project (recommended: Element.ServerRender)
dotnet restore
dotnet build Element-Blazor.sln

Install from NuGet

dotnet add package Element --prerelease

Docs and Examples

Theme Variables

Element-Blazor ships an Element Plus 2.14.0 compatible CSS variable layer at /_content/Element/css/theme.css. Load it after index.css, then override --el-* variables in your app stylesheet. See docs/p1-theme-variables.md for Button/Input/Table migration examples.

Versioning and Plan

Current Track

  • Done P0: project facade, build baseline, submodules, version baseline, and warning inventory
  • Done P1: add the Element Plus 2.14 CSS variable layer
  • Done P2: remove legacy public component names and switch to Element Plus El* control names
  • In progress P3: align visual design and APIs starting with ElButton, ElInput, and ElForm
  • Pending P4: documentation site and component overview
  • Pending P5: Element Plus component matrix gap filling
  • In progress P6: DiscuzX-like community facade and real product showcase
  • Pending P7: testing, release, and long-term maintenance

Contributing

Issues and pull requests are welcome:

Before submitting a PR, please:

  1. Keep the change scope minimal and avoid unrelated refactoring
  2. Add examples and necessary tests for new features
  3. Update relevant documentation and change notes
  4. Update roadmap progress with plain-text status markers such as Done, In progress, and Pending

Acknowledgements

  • Element Plus design concepts, component specs, and interaction patterns
  • Element UI historical ecosystem as reference material
  • All contributors and community users