Skip to content

ComponentsForms & data

SourceSource

Audit Log

A list of who changed what and when, with entries that open to show each change.

Use it to show a history of administrative actions: role edits, channel changes, bans. Newest first. An entry reads as a sentence, “ada updated the role Moderator”, and one with details opens to list them.

The kind of change is drawn as a shape before the entry (a plus, a ring, a minus) so that added, updated and removed do not depend on telling green, amber and red apart.

Root class newt-audit-log
import {
  AuditLog,
  AuditLogChange,
  AuditLogEntry,
} from "@/registry/bases/newt/ui/audit-log"

export default function AuditLogDemo() {
  return (
    <AuditLog aria-label="Audit log" className="max-w-lg">
      <AuditLogEntry
        actor="ada"
        action="updated the role"
        target="Moderator"
        kind="update"
        time="Today at 14:23"
        dateTime="2026-11-10T14:23"
        defaultOpen
      >
        <AuditLogChange>
          Granted <strong>Manage messages</strong>
        </AuditLogChange>
        <AuditLogChange>
          Changed the colour to <strong>#1abc9c</strong>
        </AuditLogChange>
      </AuditLogEntry>
      <AuditLogEntry
        actor="mio"
        action="created the channel"
        target="#release-notes"
        kind="create"
        time="Today at 11:40"
        dateTime="2026-11-10T11:40"
      >
        <AuditLogChange>
          Set the topic to <strong>What shipped, and when</strong>
        </AuditLogChange>
      </AuditLogEntry>
      <AuditLogEntry
        actor="kai"
        action="deleted the channel"
        target="#old-news"
        kind="delete"
        time="Yesterday at 09:02"
        dateTime="2026-11-09T09:02"
      />
    </AuditLog>
  )
}
<script setup lang="ts">
import {
  AuditLog,
  AuditLogChange,
  AuditLogEntry,
} from "~~/registry/bases/newt/ui/audit-log"
</script>

<template>
  <AuditLog aria-label="Audit log" class="max-w-lg">
    <AuditLogEntry
      actor="ada"
      action="updated the role"
      target="Moderator"
      kind="update"
      time="Today at 14:23"
      date-time="2026-11-10T14:23"
      default-open
    >
      <AuditLogChange>Granted <strong>Manage messages</strong></AuditLogChange>
      <AuditLogChange>
        Changed the colour to <strong>#1abc9c</strong>
      </AuditLogChange>
    </AuditLogEntry>
    <AuditLogEntry
      actor="mio"
      action="created the channel"
      target="#release-notes"
      kind="create"
      time="Today at 11:40"
      date-time="2026-11-10T11:40"
    >
      <AuditLogChange>
        Set the topic to <strong>What shipped, and when</strong>
      </AuditLogChange>
    </AuditLogEntry>
    <AuditLogEntry
      actor="kai"
      action="deleted the channel"
      target="#old-news"
      kind="delete"
      time="Yesterday at 09:02"
      date-time="2026-11-09T09:02"
    />
  </AuditLog>
</template>

Installation

npx newtui@latest add audit-lognpx shadcn@latest add @newtui/audit-lognpx shadcn-vue@latest add @newtui/audit-logpnpm dlx newtui@latest add audit-logpnpm dlx shadcn@latest add @newtui/audit-logpnpm dlx shadcn-vue@latest add @newtui/audit-logyarn dlx newtui@latest add audit-logyarn dlx shadcn@latest add @newtui/audit-logyarn dlx shadcn-vue@latest add @newtui/audit-logbunx newtui@latest add audit-logbunx shadcn@latest add @newtui/audit-logbunx shadcn-vue@latest add @newtui/audit-logdeno run -A npm:newtui@latest add audit-logdeno run -A npm:shadcn@latest add @newtui/audit-logdeno run -A npm:shadcn-vue@latest add @newtui/audit-logvlx newtui@latest add audit-logvlx shadcn@latest add @newtui/audit-logvlx shadcn-vue@latest add @newtui/audit-logvp dlx newtui@latest add audit-logvp dlx shadcn@latest add @newtui/audit-logvp dlx shadcn-vue@latest add @newtui/audit-lognubx newtui@latest add audit-lognubx shadcn@latest add @newtui/audit-lognubx shadcn-vue@latest add @newtui/audit-lognlx newtui@latest add audit-lognlx shadcn@latest add @newtui/audit-lognlx shadcn-vue@latest add @newtui/audit-logupx newtui@latest add audit-logupx shadcn@latest add @newtui/audit-logupx shadcn-vue@latest add @newtui/audit-log

The shadcn CLI needs the @newtui registry in your components.json. Set it up.

Add the components it builds on

Copy the source into your project

import * as React from "react"

import { cn } from "@/lib/utils"
import { Avatar } from "@/registry/bases/newt/ui/avatar"

/*
 * A record of who changed what, newest first, as an ordered list. Pass
 * `aria-label` to name it.
 */
const AuditLog = React.forwardRef<HTMLOListElement, React.ComponentProps<"ol">>(
  ({ className, ...props }, ref) => (
    <ol
      ref={ref}
      className={cn("m-0 flex w-full list-none flex-col gap-2 p-0", className)}
      {...props}
    />
  )
)
AuditLog.displayName = "AuditLog"

export type AuditLogKind = "create" | "update" | "delete"

/* One shape per kind, so three colours are never the only difference. */
const KIND = {
  create: {
    className: "text-newt-online",
    label: "Added",
    path: "M8 2a1 1 0 0 1 1 1v4h4a1 1 0 1 1 0 2H9v4a1 1 0 1 1-2 0V9H3a1 1 0 0 1 0-2h4V3a1 1 0 0 1 1-1Z",
  },
  update: {
    className: "text-newt-idle",
    label: "Updated",
    path: "M8 2.75a5.25 5.25 0 1 0 0 10.5 5.25 5.25 0 0 0 0-10.5Zm0 2.5a2.75 2.75 0 1 1 0 5.5 2.75 2.75 0 0 1 0-5.5Z",
  },
  delete: {
    className: "text-newt-danger",
    label: "Removed",
    path: "M3 7h10a1 1 0 1 1 0 2H3a1 1 0 0 1 0-2Z",
  },
} as const

export interface AuditLogEntryProps extends Omit<
  React.ComponentProps<"li">,
  "children"
> {
  /** Who did it. The first letter is the avatar's fallback. */
  actor: string
  /** What they did, as the middle of a sentence: "updated the role". */
  action: string
  /** What they did it to. */
  target?: string
  kind?: AuditLogKind
  /** The time as the reader should see it. */
  time: string
  /** The same moment in machine form, for the `<time>` element. */
  dateTime?: string
  /** Replaces the default initial avatar, for one with an image. */
  avatar?: React.ReactNode
  /** Read by a screen reader in place of the kind's shape. */
  kindLabel?: string
  /** Start with the changes showing. */
  defaultOpen?: boolean
  /** `AuditLogChange` rows. With none, the entry does not open. */
  children?: React.ReactNode
}

const summaryClassName =
  "flex list-none items-center gap-2.5 px-3 py-2.5 text-sm leading-5 text-newt-text-secondary [&::-webkit-details-marker]:hidden"

/*
 * An entry with changes is a native `<details>`, so it opens with Enter or
 * Space and needs no script; one without is a plain row.
 */
const AuditLogEntry = React.forwardRef<HTMLLIElement, AuditLogEntryProps>(
  (
    {
      className,
      actor,
      action,
      target,
      kind = "update",
      time,
      dateTime,
      avatar,
      kindLabel,
      defaultOpen = false,
      children,
      ...props
    },
    ref
  ) => {
    const mark = KIND[kind]
    const line = (
      <>
        <span className={cn("inline-flex shrink-0", mark.className)}>
          <svg viewBox="0 0 16 16" aria-hidden="true" className="h-4 w-4">
            <path fill="currentColor" fillRule="evenodd" d={mark.path} />
          </svg>
          <span className="sr-only">{kindLabel ?? mark.label}</span>
        </span>
        {avatar ?? <Avatar size="sm">{actor.slice(0, 1).toUpperCase()}</Avatar>}
        <span className="min-w-0 flex-1">
          <strong className="font-semibold text-newt-text-primary">
            {actor}
          </strong>{" "}
          {action}
          {target === undefined ? null : (
            <>
              {" "}
              <strong className="font-semibold text-newt-text-primary">
                {target}
              </strong>
            </>
          )}
        </span>
        <time
          dateTime={dateTime}
          className="shrink-0 text-xs text-newt-text-muted"
        >
          {time}
        </time>
      </>
    )
    /* `toArray` drops `null` and `false`, so `{cond && <Change />}` counts as none. */
    const expandable = React.Children.toArray(children).length > 0
    return (
      <li
        ref={ref}
        data-kind={kind}
        className={cn(
          "overflow-hidden rounded-[var(--newt-radius-md)] border border-newt-border bg-newt-bg-surface",
          className
        )}
        {...props}
      >
        {expandable ? (
          <details open={defaultOpen || undefined} className="group">
            <summary
              className={cn(
                summaryClassName,
                "cursor-pointer hover:bg-newt-bg-hover focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-newt-text-link"
              )}
            >
              {line}
              <svg
                viewBox="0 0 16 16"
                aria-hidden="true"
                className="h-3.5 w-3.5 shrink-0 text-newt-text-muted group-open:rotate-90 rtl:-scale-x-100 rtl:group-open:scale-x-100"
              >
                <path
                  fill="currentColor"
                  d="M5.3 3.3a1 1 0 0 1 1.4 0l4 4a1 1 0 0 1 0 1.4l-4 4a1 1 0 0 1-1.4-1.4L8.6 8 5.3 4.7a1 1 0 0 1 0-1.4Z"
                />
              </svg>
            </summary>
            <ol className="m-0 flex flex-col gap-1 pb-3 pe-3 ps-12 pt-1 text-[13px] leading-[18px] text-newt-text-secondary [list-style:decimal-leading-zero_inside]">
              {children}
            </ol>
          </details>
        ) : (
          <div className={summaryClassName}>{line}</div>
        )}
      </li>
    )
  }
)
AuditLogEntry.displayName = "AuditLogEntry"

/** One numbered line under an entry. Wrap the value that changed in `<strong>`. */
const AuditLogChange = React.forwardRef<
  HTMLLIElement,
  React.ComponentProps<"li">
>(({ className, children, ...props }, ref) => (
  <li
    ref={ref}
    className={cn(
      "marker:font-[family-name:var(--newt-font-mono)] marker:text-xs marker:text-newt-text-muted [&_strong]:font-semibold [&_strong]:text-newt-text-primary",
      className
    )}
    {...props}
  >
    {children}
  </li>
))
AuditLogChange.displayName = "AuditLogChange"

export { AuditLog, AuditLogEntry, AuditLogChange }
<script setup lang="ts">
import type { HTMLAttributes } from "vue"

import { cn } from "@/lib/utils"

/*
 * A record of who changed what, newest first, as an ordered list. Pass
 * `aria-label` to name it.
 */
const props = defineProps<{ class?: HTMLAttributes["class"] }>()
</script>

<template>
  <ol :class="cn('m-0 flex w-full list-none flex-col gap-2 p-0', props.class)">
    <slot />
  </ol>
</template>
<script setup lang="ts">
import {
  Comment,
  computed,
  Fragment,
  useSlots,
  type HTMLAttributes,
  type VNode,
} from "vue"
import { Avatar } from "~~/registry/bases/newt/ui/avatar"

import { cn } from "@/lib/utils"

import type { AuditLogKind } from "."

/*
 * An entry with changes (anything in the default slot) is a native
 * `<details>`, so it opens with Enter or Space and needs no script; one
 * without is a plain row. An `avatar` slot replaces the initial avatar.
 */
const props = withDefaults(
  defineProps<{
    class?: HTMLAttributes["class"]
    /** Who did it. The first letter is the avatar's fallback. */
    actor: string
    /** What they did, as the middle of a sentence: "updated the role". */
    action: string
    /** What they did it to. */
    target?: string
    kind?: AuditLogKind
    /** The time as the reader should see it. */
    time: string
    /** The same moment in machine form, for the `<time>` element. */
    dateTime?: string
    /** Read by a screen reader in place of the kind's shape. */
    kindLabel?: string
    /** Start with the changes showing. */
    defaultOpen?: boolean
  }>(),
  { kind: "update", defaultOpen: false }
)

/* One shape per kind, so three colours are never the only difference. */
const KIND = {
  create: {
    className: "text-newt-online",
    label: "Added",
    path: "M8 2a1 1 0 0 1 1 1v4h4a1 1 0 1 1 0 2H9v4a1 1 0 1 1-2 0V9H3a1 1 0 0 1 0-2h4V3a1 1 0 0 1 1-1Z",
  },
  update: {
    className: "text-newt-idle",
    label: "Updated",
    path: "M8 2.75a5.25 5.25 0 1 0 0 10.5 5.25 5.25 0 0 0 0-10.5Zm0 2.5a2.75 2.75 0 1 1 0 5.5 2.75 2.75 0 0 1 0-5.5Z",
  },
  delete: {
    className: "text-newt-danger",
    label: "Removed",
    path: "M3 7h10a1 1 0 1 1 0 2H3a1 1 0 0 1 0-2Z",
  },
} as const

const mark = computed(() => KIND[props.kind])

/*
 * Whether the default slot rendered anything. A slot that is passed but
 * empty, such as a `v-for` over no changes, is truthy as a function and
 * yields only comments or empty fragments, which must not make the entry
 * expandable.
 */
const slots = useSlots()

function rendersSomething(nodes: readonly VNode[]): boolean {
  return nodes.some((node) => {
    if (node.type === Comment) return false
    if (node.type === Fragment) {
      return Array.isArray(node.children) && node.children.length > 0
    }
    return true
  })
}

const expandable = computed(() => rendersSomething(slots.default?.() ?? []))

const summaryClassName =
  "flex list-none items-center gap-2.5 px-3 py-2.5 text-sm leading-5 text-newt-text-secondary [&::-webkit-details-marker]:hidden"
</script>

<template>
  <li
    :data-kind="props.kind"
    :class="
      cn(
        'overflow-hidden rounded-[var(--newt-radius-md)] border border-newt-border bg-newt-bg-surface',
        props.class
      )
    "
  >
    <component
      :is="expandable ? 'details' : 'div'"
      :open="expandable && props.defaultOpen ? true : undefined"
      class="group"
    >
      <component
        :is="expandable ? 'summary' : 'div'"
        :class="
          cn(
            summaryClassName,
            expandable &&
              'cursor-pointer hover:bg-newt-bg-hover focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-newt-text-link'
          )
        "
      >
        <span :class="cn('inline-flex shrink-0', mark.className)">
          <svg viewBox="0 0 16 16" aria-hidden="true" class="h-4 w-4">
            <path fill="currentColor" fill-rule="evenodd" :d="mark.path" />
          </svg>
          <span class="sr-only">{{ props.kindLabel ?? mark.label }}</span>
        </span>
        <slot name="avatar">
          <Avatar size="sm">{{ props.actor.slice(0, 1).toUpperCase() }}</Avatar>
        </slot>
        <span class="min-w-0 flex-1">
          <strong class="font-semibold text-newt-text-primary">{{
            props.actor
          }}</strong>
          {{ " " }}{{ props.action }}
          <template v-if="props.target !== undefined">
            {{ " " }}
            <strong class="font-semibold text-newt-text-primary">{{
              props.target
            }}</strong>
          </template>
        </span>
        <time
          :datetime="props.dateTime"
          class="shrink-0 text-xs text-newt-text-muted"
        >
          {{ props.time }}
        </time>
        <svg
          v-if="expandable"
          viewBox="0 0 16 16"
          aria-hidden="true"
          class="h-3.5 w-3.5 shrink-0 text-newt-text-muted group-open:rotate-90 rtl:-scale-x-100 rtl:group-open:scale-x-100"
        >
          <path
            fill="currentColor"
            d="M5.3 3.3a1 1 0 0 1 1.4 0l4 4a1 1 0 0 1 0 1.4l-4 4a1 1 0 0 1-1.4-1.4L8.6 8 5.3 4.7a1 1 0 0 1 0-1.4Z"
          />
        </svg>
      </component>
      <ol
        v-if="expandable"
        class="m-0 flex flex-col gap-1 pb-3 pe-3 ps-12 pt-1 text-[13px] leading-[18px] text-newt-text-secondary [list-style:decimal-leading-zero_inside]"
      >
        <slot />
      </ol>
    </component>
  </li>
</template>
<script setup lang="ts">
import type { HTMLAttributes } from "vue"

import { cn } from "@/lib/utils"

/** One numbered line under an entry. Wrap the value that changed in `<strong>`. */
const props = defineProps<{ class?: HTMLAttributes["class"] }>()
</script>

<template>
  <li
    :class="
      cn(
        'marker:font-[family-name:var(--newt-font-mono)] marker:text-xs marker:text-newt-text-muted [&_strong]:font-semibold [&_strong]:text-newt-text-primary',
        props.class
      )
    "
  >
    <slot />
  </li>
</template>
export { default as AuditLog } from "./AuditLog.vue"
export { default as AuditLogEntry } from "./AuditLogEntry.vue"
export { default as AuditLogChange } from "./AuditLogChange.vue"

export type AuditLogKind = "create" | "update" | "delete"

Update the import paths

The files import @/lib/utils and sibling components through the aliases in your components.json. Point them at wherever those live in your project.

No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Audit Log to your React project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.

No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Audit Log to your Vue project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.

Usage

import { AuditLog } from "@/components/ui/audit-log"

export function Example() {
  return <AuditLog />
}
<script setup lang="ts">
import { AuditLog, AuditLogEntry, AuditLogChange } from "@/components/ui/audit-log"
</script>

<template>
  <AuditLog />
</template>

API reference

AuditLogEntry

PropType
actor?string

Who did it. Its first letter is the default avatar.

Typestring
action?string

What they did, as the middle of a sentence: "updated the role".

Typestring
target?string

What they did it to.

Typestring
kind?"create" | "update" | "delete"

Sets the shape and colour before the entry.

Type"create" | "update" | "delete"
Default"update"
time?string

The time as the reader should see it.

Typestring
dateTime?string

The same moment in machine form, for the `<time>` element.

Typestring
avatar / #avatar?React.ReactNode / Vue slot

Replaces the initial avatar, for one with an image.

TypeReact.ReactNode / Vue slot
kindLabel?string

Read by a screen reader in place of the shape. Defaults to Added, Updated or Removed.

Typestring
defaultOpen?boolean

Start with the changes showing.

Typeboolean
Defaultfalse
children / default slot?AuditLogChange rows

The changes. With none, the entry is a plain row that does not open.

TypeAuditLogChange rows

AuditLog is the ordered list and AuditLogChange one numbered line under an entry. Wrap the value that changed in <strong> to set it apart.

Accessibility

The log is an ordered list; name it with aria-label. An entry with changes is a native <details>: its summary is a button with an expanded state, toggled by Enter or Space. The kind is announced through a hidden word (kindLabel) before the sentence. Give dateTime alongside time, so the moment is unambiguous to assistive technology even when the visible text says “Yesterday”.

kindLabel replaces the English name of the kind: Added, Updated or Removed. Translating labels lists every English default.

Tokens

Audit Log reads its colours, radii and motion from the --newt-* tokens installed with the library. Override a token and every component that reads it follows, including this one — see the token layer. In the plain HTML and CSS distribution the same component is newt-audit-log.

  • --newt-border
  • --newt-radius-md
  • --newt-bg-surface
  • --newt-text-secondary
  • --newt-bg-hover
  • --newt-text-link
  • --newt-online
  • --newt-idle
  • --newt-danger
  • --newt-text-primary
  • --newt-text-muted
  • --newt-dir
  • --newt-font-mono