timefyi-embed

Embed TimeFYI widgets — cities, glossary terms, interactive tools, and inline elements — on any website. 10 widget types, zero dependencies, Shadow DOM style isolation, 4 built-in themes (light, dark, sepia, auto), 2 styles (modern, clean), and live data from the TimeFYI database.

Every widget includes a "Powered by TimeFYI" backlink directing readers to the full reference.

Try the interactive widget builder at widget.timefyi.com

Quick Start

<!-- Place widget div where you want it to appear -->
<div data-timefyi="entity" data-slug="cities" data-theme="light"></div>

<!-- Load the embed script once, anywhere on the page -->
<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1/dist/embed.min.js"></script>

That's it. The widget fetches data from the TimeFYI API and renders with full style isolation.

Widget Types

Type	Usage	Description
entity	<div data-timefyi="entity" data-slug="..."></div>	Entity detail card — unit, city, holiday, or name
glossary	<div data-timefyi="glossary" data-slug="..."></div>	Glossary term definition with cross-references
guide	<div data-timefyi="guide" data-slug="..."></div>	Guide summary card with key takeaways
search	<div data-timefyi="search" data-slug="..."></div>	Search box linking to the full database
compare	<div data-timefyi="compare" data-slug="..."></div>	Side-by-side entity comparison
faq	<div data-timefyi="faq" data-slug="..."></div>	FAQ accordion with expand/collapse
clock	<div data-timefyi="clock" data-slug="..."></div>	Live world clock with 1-second updates
sunrise	<div data-timefyi="sunrise" data-slug="..."></div>	Sunrise/sunset times with visual day-length bar
city-compare	<div data-timefyi="city-compare" data-slug="..."></div>	Side-by-side two-city live time comparison
timezone	<div data-timefyi="timezone" data-slug="..."></div>	Inline timezone offset badge (e.g. "UTC+9")

Widget Options

Attribute	Values	Default	Description
data-timefyi	entity, compare, glossary, guide, search, faq, [tools]	required	Widget type
data-slug	e.g. "cities"	—	Entity slug from the TimeFYI database
data-theme	light, dark, sepia, auto	light	Visual theme (auto follows OS preference)
data-style	modern, clean	modern	Widget design style
data-size	default, compact, large	default	Widget size
data-placeholder	any string	"Search Cities..."	Search box placeholder

Themes

<!-- Light (default) -->
<div data-timefyi="entity" data-slug="cities" data-theme="light"></div>

<!-- Dark -->
<div data-timefyi="entity" data-slug="cities" data-theme="dark"></div>

<!-- Sepia -->
<div data-timefyi="entity" data-slug="cities" data-theme="sepia"></div>

<!-- Auto — follows OS dark/light preference -->
<div data-timefyi="entity" data-slug="cities" data-theme="auto"></div>

Styles

<!-- Modern (default) — clean lines, rounded corners, accent gradients -->
<div data-timefyi="entity" data-slug="cities" data-style="modern"></div>

<!-- Clean — minimal borders, utility-focused, data-first aesthetic -->
<div data-timefyi="entity" data-slug="cities" data-style="clean"></div>

Web Components (Custom Elements)

As an alternative to data-* attributes, you can use native HTML custom elements:

<!-- Custom element form -->
<timefyi-entity slug="cities" theme="light"></timefyi-entity>
<timefyi-compare slugs="cities,other-slug"></timefyi-compare>
<timefyi-search placeholder="Search Cities..."></timefyi-search>

<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1/dist/embed.min.js"></script>

Use style-variant (not style) to avoid conflicts with the HTML reserved style attribute.

Examples

Entity Card

<div data-timefyi="entity" data-slug="cities" data-theme="light"></div>
<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1/dist/embed.min.js"></script>

Side-by-Side Comparison

<div data-timefyi="compare" data-slugs="cities,other-slug"></div>
<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1/dist/embed.min.js"></script>

Search Box

<div data-timefyi="search" data-placeholder="Search Cities..."></div>
<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1/dist/embed.min.js"></script>

Glossary Term

<div data-timefyi="glossary" data-slug="example-term" data-theme="light"></div>
<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1/dist/embed.min.js"></script>

CDN Options

jsDelivr (recommended — global CDN, auto-updates with npm)

<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1/dist/embed.min.js"></script>

Specific version (production stability)

<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1.0.0/dist/embed.min.js"></script>

npm (for bundlers)

npm install timefyi-embed

import 'timefyi-embed';

Technical Details

• Shadow DOM: Complete style isolation — no CSS conflicts with your site
• Zero dependencies: No jQuery, React, or any external library
• 2 styles: Modern (accent gradients) and Clean (minimal, data-first)
• 4 themes: Light, Dark, Sepia, Auto (OS preference detection)
• CORS: TimeFYI API has CORS enabled for all origins
• MutationObserver: Works with dynamically added elements (SPAs)
• IntersectionObserver: Lazy loading — widgets only fetch when entering viewport (200px margin)
• Rich Snippets: DefinedTerm JSON-LD injected for glossary widgets
• Bundle size: Tree-shaken per site — only includes tools available on TimeFYI

Learn More About Cities

Visit timefyi.com — TimeFYI is a comprehensive cities reference with interactive tools, guides, and developer resources.

• API docs: timefyi.com/developers/
• Widget builder: widget.timefyi.com
• npm package: npmjs.com/package/timefyi-embed
• GitHub: github.com/fyipedia/timefyi-embed

Utility FYI Family

Part of FYIPedia — open-source developer tools ecosystem. Utility FYI covers unit conversion, timezones, holidays, and names. Hub: toolfyi.com.

Site	Domain	Focus	Package
UnitFYI	unitfyi.com	220 units, 20 categories, offline converter	npm
TimeFYI	timefyi.com	6,040 cities, live world clock, sunrise data	npm
HolidayFYI	holidayfyi.com	626 holidays, 197 countries, live today feed	npm
NameFYI	namefyi.com	35,585 names, Hanja characters, Five Elements	npm

FYIPedia Developer Tools

Package	PyPI	npm	Description
colorfyi	PyPI	npm	Color conversion, WCAG contrast, harmonies — colorfyi.com
emojifyi	PyPI	npm	Emoji encoding & metadata for 3,953 emojis — emojifyi.com
unitfyi	PyPI	npm	Unit conversion, 220 units — unitfyi.com
timefyi	PyPI	npm	Timezone ops & business hours — timefyi.com
holidayfyi	PyPI	npm	Holiday dates & Easter calculation — holidayfyi.com
namefyi	PyPI	npm	Korean romanization & Five Elements — namefyi.com
fyipedia	PyPI	—	Unified CLI for all FYI tools — fyipedia.com

Embed Widget

Embed TimeFYI widgets on any website with timefyi-embed:

<script src="https://cdn.jsdelivr.net/npm/timefyi-embed@1/dist/embed.min.js"></script>
<div data-timefyi="entity" data-slug="example"></div>

Zero dependencies · Shadow DOM · 4 themes (light/dark/sepia/auto) · Widget docs

License

MIT — see LICENSE.

Built with care by FYIPedia.