Skip to content
# AiCitationMarker ## Description BitAiCitationMarker is the small numbered chip that appears inline where a claim is attributed to a source. It is a button rather than a link, because activating it reveals the source in place instead of navigating away; its native tooltip previews the title of the source and the passage the claim rests on, and its accessible name carries the number and the title. It is sized in em of the text around it, so it follows the claim it attributes - in a heading as in a footnote. BitAiMarkdownView, BitAiStreamingMarkdown and the text parts of a message draw one for every [n] that resolves to a citation. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Citation | `BitAiCitation` | | The citation this marker points at (required). The marker shows its Number, previews the title of its source and its Quote in the native tooltip, and is named after both for assistive technologies. | | Classes | `BitAiCitationMarkerClassStyles?` | null | Custom CSS classes for different parts of the citation marker. | | OnActivate | `EventCallback<BitAiCitation>` | | The callback for when the user activates the marker (a click, or Enter / Space while it has the focus), with its citation - the place to reveal the source in place. A disabled marker raises nothing. | | Styles | `BitAiCitationMarkerClassStyles?` | null | Custom CSS styles for different parts of the citation marker. | | AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. | | Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. | | Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. | | Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. | | ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. | | HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name. | | Id | `string?` | null | Gets or sets the unique identifier for the component's root element. | | Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. | | TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. | | Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. | ## Public Members | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. | | RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. | ## Enums ### BitVisibility Enum | Name | Value | Description | | :--- | :--- | :---------- | | Visible | 0 | The content of the component is visible. | | Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). | | Collapsed | 2 | The component is hidden (display:none). | ### BitDir Enum | Name | Value | Description | | :--- | :--- | :---------- | | Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). | | Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). | | Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. | ## Sub Classes ### BitAiCitationMarkerClassStyles Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Root | `string?` | null | Custom CSS classes/styles for the root element (the button) of the BitAiCitationMarker. | ### BitAiCitation Properties A claim of a response attributed to a BitAiCitationSource: new BitAiCitation(citationId, source). A transport streams one as a BitAiCitationEvent; the message collects them in BitAiMessage.Citations. A sealed record. | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | CitationId | `string` | | The identifier of the citation, unique within its message. | | Source | `BitAiCitationSource` | | The source being cited. Several citations of one source (the same SourceId) share one entry of the source list. | | PartId | `string?` | null | The identifier of the part the span refers to, when the citation is anchored. | | StartIndex | `int?` | null | The start of the cited span of the text of the part, in UTF-16 code units. With EndIndex, it is what lets the text of a message place the marker at exactly the right position; during streaming a citation whose span runs past the text received so far is held back until the text catches up. | | EndIndex | `int?` | null | The end of the cited span, exclusive, in UTF-16 code units. | | Quote | `string?` | null | The exact text quoted from the source, shown in the preview of the marker (cut short at 220 characters). | | Locator | `string?` | null | A page number, a section or another location within the source. | | Number | `int?` | null | The one-based number of the marker - what the marker shows, what an [n] of the Markdown resolves against and what the source list numbers the source with. A session assigns it when the message is finalised, in document order whatever the order the events arrived in; set it yourself on citations you build. | | IsAnchored | `bool` | false | Whether the citation addresses a span of text: both StartIndex and EndIndex are set, and EndIndex is past StartIndex. | ## CSS Variables Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves. | Name | Default Value | Description | | :--- | :------------ | :---------- | | `--bit-AiCitationMarker-color` | var(--bit-clr-pri-fg) | The number at rest. | | `--bit-AiCitationMarker-background` | var(--bit-clr-pri-tint) | The chip at rest. | | `--bit-AiCitationMarker-hover-color` | var(--bit-clr-pri-text) | The number under the pointer. | | `--bit-AiCitationMarker-hover-background` | var(--bit-clr-pri) | The chip under the pointer. | | `--bit-AiCitationMarker-radius` | var(--bit-shp-radius-xs) | Corner of the chip. | ## Examples \n**Basic**: ```razor
Interactive Server keeps component state on the server and streams UI diffs over a SignalR circuit. If that circuit drops, the state goes with it unless you have persisted it yourself.
``` ```csharp private static readonly BitAiCitationSource renderModesSource = new("render-modes", "Blazor render modes") { Kind = BitAiSourceKind.Web, Url = "https://learn.microsoft.com/aspnet/core/blazor/components/render-modes", SiteName = "Microsoft Learn", Description = "How interactivity is chosen per component or per page.", }; private static readonly BitAiCitationSource circuitsSource = new("circuits", "SignalR circuit lifetime") { Kind = BitAiSourceKind.Document, Url = "https://learn.microsoft.com/aspnet/core/blazor/fundamentals/signalr", SiteName = "Microsoft Learn", Description = "What happens to state when a circuit drops.", }; private static readonly BitAiCitation renderModes = new("c1", renderModesSource) { Number = 1, Quote = "Interactive Server renders the component on the server and sends UI updates over a circuit.", }; private static readonly BitAiCitation circuits = new("c2", circuitsSource) { Number = 2, Quote = "When a circuit is lost, the associated component state is disposed.", }; ``` \n**Preview**: ```razor
Prerendering runs the component twice, once on the server and once in the browser.
``` ```csharp private static readonly BitAiCitationSource prerenderingSource = new("prerendering", "Prerendering") { Kind = BitAiSourceKind.Web, Url = "https://learn.microsoft.com/aspnet/core/blazor/components/prerender", SiteName = "Microsoft Learn", }; private static readonly BitAiCitation prerendering = new("c3", prerenderingSource) { Number = 3, Quote = "Prerendering is the process of initially rendering page content on the server without enabling event handlers for rendered controls.", }; private static readonly BitAiCitation prerenderingNoQuote = new("c4", prerenderingSource) { Number = 4 }; ``` \n**Activation**: ```razor
Interactive Server keeps component state on the server and loses it with the circuit, and prerendering runs it twice.
@if (activated is not null) {
@activated.Quote
} ``` ```csharp // renderModes, circuits and prerendering are the citations of the examples above. private BitAiCitation? activated; ``` \n**In Markdown**: ```razor Stream the answer @if (streamedText.Length > 0) {
Last activated: @(markdownActivated?.Source.Title ?? "-")
} ``` ```csharp // renderModes and circuits are the citations of the Basic example. private static readonly BitAiCitation[] markdownCitations = [renderModes, circuits]; private string streamedText = ""; private bool isStreaming; private BitAiCitation? markdownActivated; private async Task StreamAnswer() { isStreaming = true; markdownActivated = null; const string answer = """ **Interactive Server** keeps component state on the server and streams UI diffs over a SignalR circuit [1]. If that circuit drops, the state goes with it unless you have persisted it yourself [2]. That is the trade the render mode makes: a fast first paint, in exchange for a dependency on a live connection [1]. """; for (var i = 6; i < answer.Length; i += 6) { streamedText = answer[..i]; StateHasChanged(); await Task.Delay(30); } streamedText = answer; isStreaming = false; } ``` \n**Anchored in a message**: ```razor @implements IAsyncDisposable Ask @if (citedMessage is not null) { } ``` ```csharp // AiDemoContentTransports.Cited is a scripted transport of this site that streams anchored citations: // https://github.com/bitfoundation/bitplatform/blob/develop/src/BlazorUI/Demo/Client/Bit.BlazorUI.Demo.Client.Core/Services/AI/AiDemoContentTransports.cs private BitAiChatSession? citedSession; private BitAiMessage? citedMessage; private async Task AskCited() { if (citedSession is not null) await citedSession.DisposeAsync(); var current = new BitAiChatSession(AiDemoContentTransports.Cited()); citedSession = current; citedMessage = null; // The answer appears in the conversation once the transport starts it; from then on the message follows itself. current.StateChanged += () => { var message = current.Conversation.Messages.LastOrDefault(m => m.Role.IsAssistant); if (ReferenceEquals(message, citedMessage) || ReferenceEquals(current, citedSession) is false) return; citedMessage = message; InvokeAsync(StateHasChanged); }; await current.SubmitAsync("What does Interactive Server trade away?"); } public async ValueTask DisposeAsync() { if (citedSession is not null) await citedSession.DisposeAsync(); } ``` \n**Cascading parameters**: ```razor
State lives on the server, goes with the circuit, and is rendered twice.
``` ```csharp // renderModes, circuits and prerendering are the citations of the examples above. private readonly BitAiCitationMarkerParams[] markerParams = [ new() { Styles = new() { Root = "border-radius: 1rem; font-weight: bold" } } ]; ``` \n**Style & Class**: ```razor
A styled marker, a classy one, one with Styles and one with Classes.
Restyled by the variables of their container.
``` \n**RTL**: ```razor
حالت تعاملی سرور، وضعیت کامپوننت را روی سرور نگه می‌دارد و با قطع شدن اتصال آن را از دست می‌دهد.
``` ```csharp private static readonly BitAiCitation rtlCitation = new("c1", new BitAiCitationSource("render-modes", "حالت‌های رندر بلیزر") { Kind = BitAiSourceKind.Web, Url = "https://learn.microsoft.com/aspnet/core/blazor/components/render-modes", }) { Number = 1, }; ```