Embeddable widgets

The greyed row is the marker every widget carries. This widget mounts a CivicGate-origin iframe, which holds no client and no credential, so the shared client attributes — data-cg-key, data-cg-gateway, data-show-loading — have no effect here and are deliberately not listed. Use data-cg-site to point at a different CivicGate deployment.

• Subscribe to the place

  window.addEventListener("cg:place-change", (e) => {
    console.log(e.detail.level, e.detail.resolution.zip);
  });
  
  // browse mode: the reader pressing “Update results”
  window.addEventListener("cg:place-commit", (e) => refetch(e.detail));

  Works for all three integrations: a framed widget re-posts its events and the bundle re-fires them on your window.

• Pinned to one place

  <div data-cg-widget="place" data-view="locked" data-zip="19104" data-level="county"></div>

  A statement, not a control — for when the place is yours rather than the visitor's.

• No credential. It resolves a public ZIP into public geography.
• “Use my current location” is hidden when signed out — the gateway refuses to spend the billable geocoding key anonymously.
• Unresolved rungs render greyed as “none”, never omitted: “not covered” and “not found” must be distinguishable.
• Address is never publishable. A reader may resolve their own, but any record snaps to the ZIP.
• All CivicGate widgets on a page share one place service, so a change here moves the rest with no wiring.
• The rung persists per browser tab (sessionStorage). An explicit level always wins over a remembered one.

The greyed row is the marker every widget carries. This widget mounts a CivicGate-origin iframe, which holds no client and no credential, so the shared client attributes — data-cg-key, data-cg-gateway, data-show-loading — have no effect here and are deliberately not listed. Use data-cg-site to point at a different CivicGate deployment.

• iframe — CivicGate sign-in, no application

  <iframe src="https://www.civicgate.org/embed/login" width="100%" height="150" style="border:0" loading="lazy" title="Sign in with CivicGate"></iframe>

  No client id, so nothing to register. This signs the reader into CivicGate itself — useful beside other CivicGate widgets, which then see their saved place and name.

• iframe — sign in to YOUR application

  https://www.civicgate.org/embed/login?client_id=your-app&redirect_uri=https%3A%2F%2Fexample.org%2Fauth%2Fcallback&scope=openid+profile+email

  URL-encode the redirect URI. A raw iframe sends no PKCE challenge, so either register a confidential client without PKCE or add your own &code_challenge=.

• iframe — small, outlined, light, no photo

  https://www.civicgate.org/embed/login?size=sm&variant=outline&theme=light&avatar=0

• Script bundle — the whole integration

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  
  <div data-cg-widget="login"
       data-client-id="your-app"
       data-redirect-uri="https://example.org/auth/callback"></div>

  No configure() call: this widget takes no key and no endpoint.

• Script bundle — branded, large, your own label

  <div data-cg-widget="login"
       data-client-id="your-app"
       data-redirect-uri="https://example.org/auth/callback"
       data-scope="openid profile email civic:location"
       data-variant="brand"
       data-size="lg"
       data-label="Continue with CivicGate"
       data-theme="light"></div>

  data-label opts out of the responsive shortening, so choose one that fits your narrowest column.

• Script bundle — your own PKCE pair

  <div data-cg-widget="login"
       data-client-id="your-app"
       data-redirect-uri="https://example.org/auth/callback"
       data-state="the-value-you-stored"
       data-code-challenge="E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"></div>

  With a challenge of your own nothing is stored on your behalf — the verifier is yours and the widget never sees it.

• NO CREDENTIAL. It signs a reader in; it never reads data on anyone's behalf, so a configured key is ignored.
• The PKCE verifier never crosses an origin: the bundle mints it on YOUR origin so your callback can read it. A framed widget cannot — pass data-code-challenge and keep the verifier yourself.
• In the bundle this mounts an IFRAME: it renders a real session state, which must not be reconstructed from host-supplied markup.
• “Unknown” renders as the sign-in offer, never as “signed out” — in a third-party frame storage is partitioned, so a missing session is not proof of one.
• It reports the CivicGate session only. It cannot know whether your own site's login completed.
• Name, icon and brand colours come from the identity server's published identity, so a self-hosted deployment brands itself.
• A deployment serving neither oidc nor fedcm cannot sign readers into an application; the widget says so rather than rendering a dead button.
• Signing out ends the CivicGate session in that browser only — not your site's, and it revokes nothing already issued.
• civic:positions and civic:activity are political-belief data: consent is re-prompted every time, and refusal is normal.
• An unpublished scope is silently dropped (RFC 6749 §3.3) — a typo costs you the data with no error. Check the granted scope on the response.
• A HAND-WRITTEN iframe does not get the self-sizing. The frame always posts its height, but only the script bundle listens for it — so give a raw iframe about 150px for the signed-out button and roughly 200px if signed-in readers will see the identity row, or listen for a `cg:widget-height` message yourself and accept it ONLY from the window you created, at the origin you loaded.

The greyed rows are the attributes every widget understands.

• iframe — one card

  <iframe src="https://www.civicgate.org/embed/person/bernard_sanders" width="100%" height="150" style="border:0" loading="lazy" title="CivicGate person card"></iframe>

• iframe — large, with the detail lens

  <iframe src="https://www.civicgate.org/embed/person/josh_shapiro?size=lg&lens=1" width="100%" height="420" style="border:0" loading="lazy" title="CivicGate person card"></iframe>

  The taller frame is required: the lens is positioned against the frame's own viewport, so a short frame clips it.

• iframe — by Bioguide id, dense

  https://www.civicgate.org/embed/person/S000033?size=sm&bar=0

• Script bundle — by slug

  <div data-cg-widget="person" data-slug="bernard_sanders"></div>

• Script bundle — dense list row, linked to your own page

  <div data-cg-widget="person" data-slug="josh_shapiro" data-size="sm" data-photo="0" data-href="/our-coverage/shapiro"></div>

• Public data: no key and no account, in either integration mode.
• Every id form resolves — politician slug, FEC candidacy slug, hyphen or underscore. All redirect to the one canonical profile.
• The script bundle reads through the @cg/sdk kernel, so three cards for the same member on one page cost ONE request and share one cache with every other CivicGate widget there.
• The bundle's card has NO hover lens: it is a separate lazily-loaded chunk, so the bundle omits it. Preact and Astro get it.
• Coverage-honest: a person with no photo gets a silhouette, never a broken image; a missing role or state is omitted rather than rendered as an empty separator.

The greyed rows are the attributes every widget understands.

• One bill's wall (iframe)

  <iframe src="https://www.civicgate.org/embed/wall/bill/hr-22-119" width="100%" height="480" style="border:0" loading="lazy" title="CivicGate widget"></iframe>

• A committee's wall, infinite scroll

  https://www.civicgate.org/embed/wall/committee/hsag00?mode=auto&limit=25

• The same wall via the script bundle

  <div data-cg-widget="wall" data-type="bill" data-id="hr-22-119" data-limit="10"></div>

• Legacy spelling — still works

  https://www.civicgate.org/embed/feed?subject=bill:hr-22-119

  This was the original URL for a wall. It is live on pages we do not control, so it keeps working indefinitely. New embeds should use /embed/wall/….

• A wall is public data and takes no credential. Do not pass a key alongside a subject — the widget ignores it, deliberately, so serving a public wall can never spend someone's rate limit.
• A wall carries only the event types listed for its subject type. An empty wall means nothing happened recently, not an error.

The greyed rows are the attributes every widget understands.

• Your own following feed, with filters

  <iframe src="https://www.civicgate.org/embed/feed?key=cg_live_xxx&filters=1&limit=20&title=My%20feed" width="100%" height="520" style="border:0" loading="lazy" title="CivicGate feed"></iframe>

• The same feed via the script bundle

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  <script>CivicGate.configure({ apiKey: "cg_live_…" })</script>
  
  <div data-cg-widget="feed" data-limit="20" data-mode="auto"></div>

• API keys are read-only — the gateway rejects every mutation on a key-authenticated request. Restrict a key by origin.
• A key-authenticated request is treated as ANONYMOUS for visibility, so an embedded key can never widen what a reader is allowed to see.
• No live preview with a key: any example here would show one account's private subscriptions to everyone, so the playground above uses your own session instead.

The greyed rows are the attributes every widget understands.

• 1 · Pinned to one district

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  
  <div data-cg-widget="place-wall"
       data-state="PA"
       data-district="3"
       data-level="district"></div>

  Standalone. Nothing on the page can move it — the right choice for a site about one place.

• 2 · Following a Place locator on the page

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  
  <!-- The reader picks the place here… -->
  <div data-cg-widget="place" data-view="header" data-hover="expand"></div>
  
  <!-- …and the wall follows it. No JavaScript of your own. -->
  <div data-cg-widget="place-wall" data-place="derive" data-state="PA"></div>

  The two widgets never reference each other — the locator EMITS cg:place-change and the wall LISTENS — so either one works with the other absent. data-state is just the starting place until the reader moves it.

• 3 · Driving it from your own place picker

  window.dispatchEvent(new CustomEvent("cg:place-change", {
    detail: { level: "state", resolution: { state: "OH", countyFips: null, district: null } },
  }));

  The wall listens for the event, not for our widget, so your own UI can drive it by emitting the same shape.

• 4 · As an iframe (always pinned)

  <iframe src="https://www.civicgate.org/embed/place-wall?state=PA&district=3" width="100%" height="520" style="border:0"></iframe>

  A frame cannot hear the host page's events, so an iframe wall is pinned by its query string. Use the script bundle when you want it to follow a locator.

• THREE WAYS TO NAME THE PLACE — pinned by attributes, derived from a locator on the page (data-place="derive"), or both, where the attributes are the starting place until the first event arrives.
• They work together and standalone. The locator and the wall never reference each other: one emits cg:place-change, the other listens. Either is useful with the other absent.
• A place is not a subject, so this is a third API call (placeFeed), not a filter over the feed or a subject wall.
• Two sources, merged and de-duplicated: the place's REPRESENTATIVES (a subject list, like a follow list) and events INDEXED to the place (state bills, national actions).
• Federal bills carry no place deliberately — tagging all ~20k `us` would be a firehose wearing a local label. Federal relevance arrives through the people who represent the place.
• A House member's events are DISTRICT-scoped, not state-scoped: otherwise every district's wall shows every other district's member.
• level is clamped to what the place resolved and the clamped value is returned, so a district request against a state-only place cannot silently answer with state events.
• On CivicGate's own /place page this is the "Latest" section — the same component, with a level control and kind filters, following the locator in the page header.

The greyed row is the marker every widget carries. This widget mounts a CivicGate-origin iframe, which holds no client and no credential, so the shared client attributes — data-cg-key, data-cg-gateway, data-show-loading — have no effect here and are deliberately not listed. Use data-cg-site to point at a different CivicGate deployment.

• iframe — one ZIP

  <iframe src="https://www.civicgate.org/embed/issue-report?zip=19104" width="100%" height="620" style="border:0" loading="lazy" title="Report an issue — CivicGate"></iframe>

• iframe — pinned to one rung, no heading

  https://www.civicgate.org/embed/issue-report?zip=19104&level=district&nav=0&title=

  nav=0 removes the ladder and level=district fixes the rung, so every report from this embed is filed against PA-3. The empty title suppresses the widget's own heading because the host page has one.

• iframe — a state-wide placement

  https://www.civicgate.org/embed/issue-report?state=PA&source=pa-news

  With no ZIP only the State and Federal rungs are offered. The source tag makes this embed's reports identifiable later.

• Script bundle — the whole integration

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  
  <div data-cg-widget="issue-report" data-zip="19104"></div>

  No configure() call: this widget takes no key and no endpoint.

• Script bundle — pinned, sized, tagged

  <div data-cg-widget="issue-report"
       data-zip="19104"
       data-level="zip"
       data-nav="0"
       data-discussion="0"
       data-title=""
       data-source="ourpaper"
       data-width="32rem"
       data-height="480"></div>

• NO CREDENTIAL. Reporting is a mutation, and keys are read-only — a configured key is ignored rather than passed through.
• In the bundle this mounts an IFRAME (unlike person / wall / feed): it is a form, it may carry a session, and it must not inherit host styles.
• Anti-duplicate search runs from 3 characters, debounced and place-scoped — the reader can join an existing report instead of filing a second.
• Anonymous is first class: nothing is gated on a session, and a signed-in member filing anonymously has their token withheld, not ignored server-side.
• “Locate me” is offered to signed-in readers only: it turns browser coordinates into a ZIP through CivicGate's server-side geocoder, and the gateway refuses to spend that billable key anonymously. A button that always errors is worse than an absent one. In the script bundle the frame is granted allow="geolocation" — permission is still the reader's to give.
• Not yet wired: photo/file attachments and discussion threads on reports. The UI says so rather than offering a dead control.
• A report's exact location is never published. The jurisdiction shown on the form is what appears on the record.
• Validation failures are surfaced VERBATIM from the gateway (“A ZIP-level report needs a ZIP.”) — restating the server's rules in the widget would be a second copy that drifts.
• A hand-written iframe does not self-size — only the bundle listens for the height message. Give a raw iframe a generous fixed height.

The greyed row is the marker every widget carries. This widget mounts a CivicGate-origin iframe, which holds no client and no credential, so the shared client attributes — data-cg-key, data-cg-gateway, data-show-loading — have no effect here and are deliberately not listed. Use data-cg-site to point at a different CivicGate deployment.

• iframe — one ZIP

  <iframe src="https://www.civicgate.org/embed/issue-topics?zip=19104" width="100%" height="520" style="border:0" loading="lazy" title="Reported issues — CivicGate"></iframe>

• iframe — one rung, longer page, no heading

  https://www.civicgate.org/embed/issue-topics?zip=19104&level=district&limit=25&nav=0&title=

• iframe — open reports only, with the identity line

  https://www.civicgate.org/embed/issue-topics?zip=19104&status=reported&identity=1

  The identity line is what lets a reader sign in from the listing before moving to the reporter.

• Script bundle — the whole integration

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  
  <div data-cg-widget="issue-topics" data-zip="19104" data-limit="10"></div>

• Script bundle — the pair, side by side

  <div data-cg-widget="issue-topics" data-zip="19104" data-limit="5" data-nav="0"></div>
  <div data-cg-widget="issue-report"  data-zip="19104" data-nav="0"></div>

  Two independent frames. They do not share state, so pin BOTH to the same place — a ladder left on in one of them would let the two drift apart in front of the reader.

• Public data: no key, no account, in either integration mode. Like the reporter, a configured key is ignored rather than forwarded.
• In the bundle this mounts an IFRAME, like the reporter. It self-sizes; a hand-written iframe does not.
• Prints only what the gateway returned: no invented counts, no discussion link for a report without a thread, and an honest empty state.
• The place filter always includes FEDERAL reports alongside the selected rung, so every row shows its own place label.
• Rows show the author's display name, or “Anonymous” where the reporter chose it. A report's exact location is never published.
• A failed load says so and offers “Try again” rather than rendering an empty list, which would read as “nothing reported here”.
• A hand-written iframe does not self-size — only the bundle listens for the height message.

This widget takes no parameters.

• iframe only — the choropleth renderer is too large to ship in the bundle.

• Texas

  https://www.civicgate.org/embed/district-funding/TX

• New York

  https://www.civicgate.org/embed/district-funding/ny

  Lower case works — the code is upper-cased server-side.

• iframe only, for the same reason as the funding map.

• By Bioguide id

  https://www.civicgate.org/embed/network/S000148

• By slug

  https://www.civicgate.org/embed/network/chuck_schumer

  The slug is resolved to the member's canonical id server-side before the graph is built.

• iframe only.

The greyed row is the marker every widget carries. This widget mounts a CivicGate-origin iframe, which holds no client and no credential, so the shared client attributes — data-cg-key, data-cg-gateway, data-show-loading — have no effect here and are deliberately not listed. Use data-cg-site to point at a different CivicGate deployment.

• 1 · Static place — a site about one district

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  
  <div data-cg-widget="ballot" data-place="us-pa-d03"></div>

  Pinned. Nothing on the page can move it. The place key is the last segment of the URL pattern us-<state>-d<NN> — district numbers are zero-padded, and 00 is at-large.

• 2 · Dynamic — follows the Place locator on the page

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  
  <!-- The reader picks the place here… -->
  <div data-cg-widget="place" data-view="header"></div>
  
  <!-- …and the ballot follows it. No JavaScript of your own. -->
  <div data-cg-widget="ballot" data-place="derive" data-state="PA"></div>

  The two widgets never reference each other — the locator EMITS cg:place-change and the ballot LISTENS — so either works with the other absent. data-state is only the starting place until the reader moves the locator.

• 3 · Driving it from your own place picker

  window.dispatchEvent(new CustomEvent("cg:place-change", {
    detail: { level: "district", resolution: { state: "OH", countyFips: null, district: 3 } },
  }));

  It listens for the EVENT, not for our widget, so your own UI can drive it by emitting the same shape.

• 4 · As an iframe — always pinned

  <iframe src="https://www.civicgate.org/embed/ballot/us-pa-d03?within-days=90"
          width="100%" height="620" style="border:0"
          title="What's on the ballot"></iframe>

  A hand-written frame cannot hear the host page's events and does not self-size — give it a generous fixed height, and use the script bundle if you want it to follow a locator.

• 5 · With an API key configured on the page — the key is IGNORED

  <script src="https://www.civicgate.org/widget/civicgate-widget.js" defer></script>
  <script>CivicGate.configure({ apiKey: "cg_live_…" })</script>
  
  <!-- Your feed widget uses the key. The ballot does not, and must not. -->
  <div data-cg-widget="feed" data-limit="10"></div>
  <div data-cg-widget="ballot" data-place="us-pa-d03"></div>

  Elections, contests and candidate filings are public records. Serving public data must never spend an account's rate limit on data that needed no identity at all — the same rule the subject wall follows — so this widget deliberately does not read a key even when the page has one.

• 6 · The next 90 days only, no controls — a homepage tout

  <div data-cg-widget="ballot"
       data-place="derive"
       data-within-days="90"
       data-controls="0"
       data-history="0"
       data-candidates="3"
       data-title="Coming up where you live"></div>

  The empty state names the horizon it checked, so “nothing in the next 90 days” can never be read as “nothing is scheduled”.

• 7 · History — who was on the ballot, never who won

  <div data-cg-widget="ballot" data-place="us-pa-d03" data-past="1"></div>

  Past AND upcoming, newest first. CivicGate holds no results data, and the widget states that above the list rather than leaving a reader to infer an outcome from the ordering. A past contest with no filings reads “No candidates are recorded”, not “not filed yet” — the wrong tense over a 2022 race is how a reader decides the widget is broken.

• COVERAGE IS THE POINT, and it renders in EVERY state — loading, empty, error and full — before the races, never collapsed. CivicGate holds FEDERAL contests and no state or local ones: a Philadelphia voter's real November ballot has a governor's race, a lieutenant governor, state legislative seats and city races, and we can show exactly one of those. An unlabelled partial ballot is a confident, authoritative WRONG answer to the highest-stakes question this platform answers.
• An empty result says “that is what CivicGate holds for this place at this breadth”, never “there are no races here”. Those are different statements and only one of them is ours to make. The WHY comes from coverage.note, rendered VERBATIM — asking for a state breadth at a district place correctly returns nothing, because a House race is not decided statewide, and the note says exactly that. The widget adds a one-click “Narrow to My district” action rather than paraphrasing the advice: a sentence we maintain beside a sentence the gateway maintains is how the two end up disagreeing.
• coverage.federal = "none" MEANS SOMETHING DIFFERENT from coverage.state = "none", and the widget renders them differently. State and local are structurally absent — nothing is ingested — so those read “Not in CivicGate yet”. Federal “none” means no rows matched at the breadth you asked for, and reads “None found at this level”: CivicGate holds those races, they are simply not decided in that area. Printing “not in CivicGate” there would be a false coverage claim about the one tier we hold in full.
• NO ELECTION RESULTS. CivicGate does not hold winners. History mode shows who was on the ballot and says so; nothing in this widget implies an outcome.
• A candidate with no CivicGate profile is rendered WITHOUT a link and says why. Minting /people/<fec-id> for them would be a 404 dressed as a profile.
• Money is the FEC receipts figure as filed. A candidate with none reads “No FEC receipts reported”, never $0 — those are different facts.
• No credential. A configured apiKey is deliberately not read (see example 5).
• The place label shown is always the one the SERVER resolved, alongside its place key — asking for a county breadth against a district-only place resolves to the state, and printing the request would tell the reader we are showing something we are not.
• county and district are SIBLINGS, not a hierarchy: a congressional district cuts across counties, so a resolved ZIP legitimately belongs to both.
• In the script bundle this mounts an IFRAME (like place, issue-report and login): it is a rich styled surface, and the bundle ships no stylesheet into a host document. data-place="derive" still works because the bundle forwards the host's cg:place-* events INTO the frame — which a hand-written iframe cannot do.
• Candidates are ordered by the server: incumbent first, then money raised, then name. That is what makes truncating to six safe rather than arbitrary.