Edit

Share via

Consume ASP.NET Core Razor components from a Razor class library (RCL)

Note

This isn't the latest version of this article. For the current release, see the .NET 10 version of this article.

Warning

This version of ASP.NET Core is no longer supported. For more information, see the .NET and .NET Core Support Policy. For the current release, see the .NET 9 version of this article.

Components can be shared in a Razor class library (RCL) across projects. Include components and static assets in an app from:

  • Another project in the solution.
  • A referenced .NET library.
  • A NuGet package.

Just as components are regular .NET types, components provided by an RCL are normal .NET assemblies.

Create an RCL

  1. Create a new project.
  2. In the Create a new project dialog, select Razor Class Library from the list of ASP.NET Core project templates. Select Next.
  3. In the Configure your new project dialog, provide a project name in the Project name field. Examples in this topic use the project name ComponentLibrary. Select Next.
  4. In the Additional information dialog, don't select Support pages and views. Select Create.
  5. Add the RCL to a solution:
    1. Open the solution.
    2. Right-click the solution in Solution Explorer. Select Add > Existing Project.
    3. Navigate to the RCL's project file.
    4. Select the RCL's project file (.csproj).
  6. Add a reference to the RCL from the app:
    1. Right-click the app project. Select Add > Project Reference.
    2. Select the RCL project. Select OK.

Consume a Razor component from an RCL

To consume components from an RCL in another project, use either of the following approaches:

  • Use the full component type name, which includes the RCL's namespace.
  • Individual components can be added by name without the RCL's namespace if Razor's @using directive declares the RCL's namespace. Use the following approaches:
    • Add the @using directive to individual components.
    • include the @using directive in the top-level _Imports.razor file to make the library's components available to an entire project. Add the directive to an _Imports.razor file at any level to apply the namespace to a single component or set of components within a folder. When an _Imports.razor file is used, individual components don't require an @using directive for the RCL's namespace.

In the following examples, ComponentLibrary is an RCL containing the Component1 component. The Component1 component is an example component automatically added to an RCL created from the RCL project template that isn't created to support pages and views.

Component1.razor in the ComponentLibrary RCL:

<div class="my-component">
    This component is defined in the <strong>ComponentLibrary</strong> package.
</div>

In the app that consumes the RCL, reference the Component1 component using its namespace, as the following example shows.

ConsumeComponent1.razor:

@page "/consume-component-1"

<h1>Consume component (full namespace example)</h1>

<ComponentLibrary.Component1 />

Alternatively, add a @using directive and use the component without its namespace. The following @using directive can also appear in any _Imports.razor file in or above the current folder.

ConsumeComponent2.razor:

@page "/consume-component-2"
@using ComponentLibrary

<h1>Consume component (<code>@@using</code> example)</h1>

<Component1 />

For library components that use CSS isolation, the component styles are automatically made available to the consuming app. There's no need to manually link or import the library's individual component stylesheets or its bundled CSS file in the app that consumes the library. The app uses CSS imports to reference the RCL's bundled styles. The bundled styles aren't published as a static web asset of the app that consumes the library. For a class library named ClassLib and a Blazor app with a BlazorSample.styles.css stylesheet, the RCL's stylesheet is imported at the top of the app's stylesheet automatically at build time:

@import '_content/ClassLib/ClassLib.bundle.scp.css';

For the preceding examples, Component1's stylesheet (Component1.razor.css) is bundled automatically.

Component1.razor.css in the ComponentLibrary RCL:

.my-component {
    border: 2px dashed red;
    padding: 1em;
    margin: 1em 0;
    background-image: url('background.png');
}

The background image is also included from the RCL project template and resides in the wwwroot folder of the RCL.

wwwroot/background.png in the ComponentLibrary RCL:

Diagonally-striped background image from the RCL project template

To provide additional library component styles from stylesheets in the library's wwwroot folder, add stylesheet <link> tags to the RCL's consumer, as the next example demonstrates.

Important

Generally, library components use CSS isolation to bundle and provide component styles. Component styles that rely upon CSS isolation are automatically made available to the app that uses the RCL. There's no need to manually link or import the library's individual component stylesheets or its bundled CSS file in the app that consumes the library. The following example is for providing global stylesheets outside of CSS isolation, which usually isn't a requirement for typical apps that consume RCLs.

The following background image is used in the next example. If you implement the example shown in this section, right-click the image to save it locally.

wwwroot/extra-background.png in the ComponentLibrary RCL:

Diagonally-striped background image added to the library by the developer

Add a new stylesheet to the RCL with an extra-style class.

wwwroot/additionalStyles.css in the ComponentLibrary RCL:

.extra-style {
    border: 2px dashed blue;
    padding: 1em;
    margin: 1em 0;
    background-image: url('extra-background.png');
}

Add a component to the RCL that uses the extra-style class.

ExtraStyles.razor in the ComponentLibrary RCL:

<div class="extra-style">
    <p>
        This component is defined in the <strong>ComponentLibrary</strong> package.
    </p>
</div>

Add a page to the app that uses the ExtraStyles component from the RCL.

ConsumeComponent3.razor:

@page "/consume-component-3"
@using ComponentLibrary

<h1>Consume component (<code>additionalStyles.css</code> example)</h1>

<ExtraStyles />

Link to the library's stylesheet in the app's <head> markup (location of <head> content):

Blazor Web Apps:

<link href="@Assets["_content/ComponentLibrary/additionalStyles.css"]" rel="stylesheet">

Standalone Blazor WebAssembly apps:

<link href="_content/ComponentLibrary/additionalStyles.css" rel="stylesheet">

<link href="_content/ComponentLibrary/additionalStyles.css" rel="stylesheet">

For library components that use CSS isolation, the component styles are automatically made available to the consuming app. There's no need to manually link or import the library's individual component stylesheets or its bundled CSS file in the app that consumes the library. The app uses CSS imports to reference the RCL's bundled styles. The bundled styles aren't published as a static web asset of the app that consumes the library. For a class library named ClassLib and a Blazor app with a BlazorSample.styles.css stylesheet, the RCL's stylesheet is imported at the top of the app's stylesheet automatically at build time:

@import '_content/ClassLib/ClassLib.bundle.scp.css';

For the preceding examples, Component1's stylesheet (Component1.razor.css) is bundled automatically.

Component1.razor.css in the ComponentLibrary RCL:

.my-component {
    border: 2px dashed red;
    padding: 1em;
    margin: 1em 0;
    background-image: url('background.png');
}

The background image is also included from the RCL project template and resides in the wwwroot folder of the RCL.

wwwroot/background.png in the ComponentLibrary RCL:

Diagonally-striped background image from the RCL project template

The following background image and stylesheet are used by the RCL's Component1 example component. There's no need to add these static assets to a new RCL created from the RCL project template, as they're added automatically by the project template.

wwwroot/background.png in the ComponentLibrary RCL:

Diagonally-striped background image added to the library by the RCL project template

wwwroot/styles.css in the ComponentLibrary RCL:

.my-component {
    border: 2px dashed red;
    padding: 1em;
    margin: 1em 0;
    background-image: url('background.png');
}

To provide Component1's my-component CSS class, link to the library's stylesheet in the app's <head> markup (location of <head> content):

<link href="_content/ComponentLibrary/styles.css" rel="stylesheet" />

Make routable components available from the RCL

To make routable components in the RCL available for direct requests, the RCL's assembly must be disclosed to the app's router.

Open the app's App component (App.razor). Assign an Assembly collection to the AdditionalAssemblies parameter of the Router component to include the RCL's assembly. In the following example, the ComponentLibrary.Component1 component is used to discover the RCL's assembly.

AdditionalAssemblies="new[] { typeof(ComponentLibrary.Component1).Assembly }"

For more information, see ASP.NET Core Blazor routing and navigation.

Create an RCL with static assets in the wwwroot folder

An RCL's static assets are available to any app that consumes the library.

Place static assets in the wwwroot folder of the RCL and reference the static assets with the following path in the app: _content/{PACKAGE ID}/{PATH AND FILE NAME}. The {PACKAGE ID} placeholder is the library's package ID. The package ID defaults to the project's assembly name if <PackageId> isn't specified in the project file. The {PATH AND FILE NAME} placeholder is path and file name under wwwroot. This path format is also used in the app for static assets supplied by NuGet packages added to the RCL.

The following example demonstrates the use of RCL static assets with an RCL named ComponentLibrary and a Blazor app that consumes the RCL. The app has a project reference for the ComponentLibrary RCL.

The following Jeep® image is used in this section's example. If you implement the example shown in this section, right-click the image to save it locally.

wwwroot/jeep-yj.png in the ComponentLibrary RCL: